From mboxrd@z Thu Jan 1 00:00:00 1970 From: Alasdair Kergon Date: Mon, 13 Mar 2017 21:10:13 -0400 Subject: master - man: Revise internal man page generation process. Message-ID: <201703140110.v2E1ADfQ014423@int-mx09.intmail.prod.int.phx2.redhat.com> List-Id: To: lvm-devel@redhat.com MIME-Version: 1.0 Content-Type: text/plain; charset="us-ascii" Content-Transfer-Encoding: 7bit Gitweb: https://sourceware.org/git/?p=lvm2.git;a=commitdiff;h=ca905681ccf9afd2b8313b5a7a89ac609c9a7ba5 Commit: ca905681ccf9afd2b8313b5a7a89ac609c9a7ba5 Parent: 38292ca1d0a78aa6b06a4180b8e87cb9dd417a22 Author: Alasdair G Kergon AuthorDate: Tue Mar 14 00:47:46 2017 +0000 Committer: Alasdair G Kergon CommitterDate: Tue Mar 14 00:47:46 2017 +0000 man: Revise internal man page generation process. For each section 8 man page, a .8_gen file is created from one of: .8_main - Old-style man page - content used directly .8_des and .8_end - Description and end section of a generated page .8_pregen - Pre-generated page used if the generator fails Other man sections are not generated and use the suffix .5_main or .7_main. Developers should use 'make generate' to regenerate the .8_pregen files. --- Makefile.in | 5 +- man/Makefile.in | 112 +- man/blkdeactivate.8.in | 105 -- man/blkdeactivate.8_main | 105 ++ man/clvmd.8.in | 199 --- man/clvmd.8_main | 199 +++ man/cmirrord.8.in | 39 - man/cmirrord.8_main | 39 + man/dmeventd.8.in | 150 -- man/dmeventd.8_main | 150 ++ man/dmfilemapd.8.in | 212 --- man/dmfilemapd.8_main | 212 +++ man/dmsetup.8.in | 1026 ------------ man/dmsetup.8_main | 1026 ++++++++++++ man/dmstats.8.in | 1284 --------------- man/dmstats.8_main | 1284 +++++++++++++++ man/fsadm.8.in | 114 -- man/fsadm.8_main | 114 ++ man/lvchange.8.des | 2 - man/lvchange.8.end | 6 - man/lvchange.8_des | 2 + man/lvchange.8_end | 6 + man/lvchange.8_pregen | 1272 +++++++++++++++ man/lvconvert.8.des | 65 - man/lvconvert.8.end | 116 -- man/lvconvert.8_des | 65 + man/lvconvert.8_end | 116 ++ man/lvconvert.8_pregen | 2059 ++++++++++++++++++++++++ man/lvcreate.8.des | 39 - man/lvcreate.8.end | 98 -- man/lvcreate.8_des | 39 + man/lvcreate.8_end | 98 ++ man/lvcreate.8_pregen | 2865 ++++++++++++++++++++++++++++++++++ man/lvdisplay.8.des | 5 - man/lvdisplay.8_des | 5 + man/lvdisplay.8_pregen | 639 ++++++++ man/lvextend.8.des | 12 - man/lvextend.8.end | 16 - man/lvextend.8_des | 12 + man/lvextend.8_end | 16 + man/lvextend.8_pregen | 781 +++++++++ man/lvm-config.8.des | 5 - man/lvm-config.8_des | 5 + man/lvm-config.8_pregen | 522 +++++++ man/lvm-dumpconfig.8.des | 5 - man/lvm-dumpconfig.8_des | 5 + man/lvm-dumpconfig.8_pregen | 522 +++++++ man/lvm-fullreport.8.des | 6 - man/lvm-fullreport.8_des | 6 + man/lvm-fullreport.8_pregen | 623 ++++++++ man/lvm-lvpoll.8.des | 4 - man/lvm-lvpoll.8.end | 33 - man/lvm-lvpoll.8_des | 4 + man/lvm-lvpoll.8_end | 33 + man/lvm-lvpoll.8_pregen | 373 +++++ man/lvm.8.in | 553 ------- man/lvm.8_main | 553 +++++++ man/lvm.conf.5.in | 213 --- man/lvm.conf.5_main | 213 +++ man/lvm2-activation-generator.8.in | 55 - man/lvm2-activation-generator.8_main | 55 + man/lvmcache.7.in | 419 ----- man/lvmcache.7_main | 419 +++++ man/lvmconf.8.in | 70 - man/lvmconf.8_main | 70 + man/lvmconfig.8.des | 3 - man/lvmconfig.8_des | 3 + man/lvmconfig.8_pregen | 520 ++++++ man/lvmdbusd.8.in | 38 - man/lvmdbusd.8_main | 38 + man/lvmdiskscan.8.des | 7 - man/lvmdiskscan.8_des | 7 + man/lvmdiskscan.8_pregen | 314 ++++ man/lvmdump.8.in | 112 -- man/lvmdump.8_main | 112 ++ man/lvmetad.8.in | 126 -- man/lvmetad.8_main | 126 ++ man/lvmlockctl.8.in | 102 -- man/lvmlockctl.8_main | 102 ++ man/lvmlockd.8.in | 889 ----------- man/lvmlockd.8_main | 889 +++++++++++ man/lvmpolld.8.in | 90 -- man/lvmpolld.8_main | 90 ++ man/lvmraid.7.in | 1711 -------------------- man/lvmraid.7_main | 1711 ++++++++++++++++++++ man/lvmreport.7.in | 1810 --------------------- man/lvmreport.7_main | 1810 +++++++++++++++++++++ man/lvmsadc.8.des | 3 - man/lvmsadc.8_des | 3 + man/lvmsadc.8_pregen | 280 ++++ man/lvmsar.8.des | 3 - man/lvmsar.8_des | 3 + man/lvmsar.8_pregen | 296 ++++ man/lvmsystemid.7.in | 354 ----- man/lvmsystemid.7_main | 354 +++++ man/lvmthin.7.in | 1359 ---------------- man/lvmthin.7_main | 1359 ++++++++++++++++ man/lvreduce.8.des | 19 - man/lvreduce.8.end | 5 - man/lvreduce.8_des | 19 + man/lvreduce.8_end | 5 + man/lvreduce.8_pregen | 426 +++++ man/lvremove.8.des | 27 - man/lvremove.8.end | 11 - man/lvremove.8_des | 27 + man/lvremove.8_end | 11 + man/lvremove.8_pregen | 424 +++++ man/lvrename.8.des | 2 - man/lvrename.8.end | 10 - man/lvrename.8_des | 2 + man/lvrename.8_end | 10 + man/lvrename.8_pregen | 356 +++++ man/lvresize.8.des | 7 - man/lvresize.8.end | 6 - man/lvresize.8_des | 7 + man/lvresize.8_end | 6 + man/lvresize.8_pregen | 702 +++++++++ man/lvs.8.des | 1 - man/lvs.8.end | 76 - man/lvs.8_des | 1 + man/lvs.8_end | 76 + man/lvs.8_pregen | 733 +++++++++ man/lvscan.8.des | 5 - man/lvscan.8_des | 5 + man/lvscan.8_pregen | 399 +++++ man/pvchange.8.des | 1 - man/pvchange.8.end | 6 - man/pvchange.8_des | 1 + man/pvchange.8_end | 6 + man/pvchange.8_pregen | 487 ++++++ man/pvck.8.des | 1 - man/pvck.8.end | 8 - man/pvck.8_des | 1 + man/pvck.8_end | 8 + man/pvck.8_pregen | 311 ++++ man/pvcreate.8.des | 21 - man/pvcreate.8.end | 13 - man/pvcreate.8_des | 21 + man/pvcreate.8_end | 13 + man/pvcreate.8_pregen | 539 +++++++ man/pvdisplay.8.des | 5 - man/pvdisplay.8_des | 5 + man/pvdisplay.8_pregen | 610 ++++++++ man/pvmove.8.des | 16 - man/pvmove.8.end | 93 -- man/pvmove.8_des | 16 + man/pvmove.8_end | 93 ++ man/pvmove.8_pregen | 551 +++++++ man/pvremove.8.des | 7 - man/pvremove.8_des | 7 + man/pvremove.8_pregen | 323 ++++ man/pvresize.8.des | 2 - man/pvresize.8.end | 16 - man/pvresize.8_des | 2 + man/pvresize.8_end | 16 + man/pvresize.8_pregen | 334 ++++ man/pvs.8.des | 1 - man/pvs.8.end | 11 - man/pvs.8_des | 1 + man/pvs.8_end | 11 + man/pvs.8_pregen | 656 ++++++++ man/pvscan.8.des | 105 -- man/pvscan.8_des | 105 ++ man/pvscan.8_pregen | 542 +++++++ man/vgcfgbackup.8.des | 16 - man/vgcfgbackup.8_des | 16 + man/vgcfgbackup.8_pregen | 389 +++++ man/vgcfgrestore.8.des | 11 - man/vgcfgrestore.8.end | 9 - man/vgcfgrestore.8_des | 11 + man/vgcfgrestore.8_end | 9 + man/vgcfgrestore.8_pregen | 473 ++++++ man/vgchange.8.des | 2 - man/vgchange.8.end | 16 - man/vgchange.8_des | 2 + man/vgchange.8_end | 16 + man/vgchange.8_pregen | 1151 ++++++++++++++ man/vgck.8.des | 1 - man/vgck.8_des | 1 + man/vgck.8_pregen | 310 ++++ man/vgconvert.8.des | 7 - man/vgconvert.8_des | 7 + man/vgconvert.8_pregen | 394 +++++ man/vgcreate.8.des | 4 - man/vgcreate.8.end | 6 - man/vgcreate.8_des | 4 + man/vgcreate.8_end | 6 + man/vgcreate.8_pregen | 626 ++++++++ man/vgdisplay.8.des | 4 - man/vgdisplay.8_des | 4 + man/vgdisplay.8_pregen | 606 +++++++ man/vgexport.8.des | 8 - man/vgexport.8_des | 8 + man/vgexport.8_pregen | 363 +++++ man/vgextend.8.des | 11 - man/vgextend.8.end | 6 - man/vgextend.8_des | 11 + man/vgextend.8_end | 6 + man/vgextend.8_pregen | 473 ++++++ man/vgimport.8.des | 5 - man/vgimport.8_des | 5 + man/vgimport.8_pregen | 372 +++++ man/vgimportclone.8.des | 6 - man/vgimportclone.8.end | 9 - man/vgimportclone.8_des | 6 + man/vgimportclone.8_end | 9 + man/vgimportclone.8_pregen | 330 ++++ man/vgmerge.8.des | 3 - man/vgmerge.8.end | 7 - man/vgmerge.8_des | 3 + man/vgmerge.8_end | 7 + man/vgmerge.8_pregen | 315 ++++ man/vgmknodes.8.des | 5 - man/vgmknodes.8_des | 5 + man/vgmknodes.8_pregen | 346 ++++ man/vgreduce.8.des | 1 - man/vgreduce.8_des | 1 + man/vgreduce.8_pregen | 483 ++++++ man/vgremove.8.des | 9 - man/vgremove.8_des | 9 + man/vgremove.8_pregen | 364 +++++ man/vgrename.8.des | 9 - man/vgrename.8.end | 10 - man/vgrename.8_des | 9 + man/vgrename.8_end | 10 + man/vgrename.8_pregen | 361 +++++ man/vgs.8.des | 1 - man/vgs.8.end | 17 - man/vgs.8_des | 1 + man/vgs.8_end | 17 + man/vgs.8_pregen | 642 ++++++++ man/vgscan.8.des | 1 - man/vgscan.8_des | 1 + man/vgscan.8_pregen | 356 +++++ man/vgsplit.8.des | 13 - man/vgsplit.8_des | 13 + man/vgsplit.8_pregen | 444 ++++++ 237 files changed, 39462 insertions(+), 12172 deletions(-) diff --git a/Makefile.in b/Makefile.in index b525278..31d428d 100644 --- a/Makefile.in +++ b/Makefile.in @@ -100,7 +100,7 @@ CLEAN_DIRS += autom4te.cache check check_system check_cluster check_local check_lvmetad check_lvmpolld check_lvmlockd_test check_lvmlockd_dlm check_lvmlockd_sanlock unit: all $(MAKE) -C test $(@) -conf.generate: tools +conf.generate man.generate: tools # how to use parenthesis in makefiles leftparen:=( @@ -130,8 +130,9 @@ rpm: dist $(top_srcdir)/spec/source.inc >$(rpmbuilddir)/SOURCES/source.inc rpmbuild -v --define "_topdir $(rpmbuilddir)" -ba $(top_srcdir)/spec/lvm2.spec -generate: conf.generate +generate: conf.generate man.generate $(MAKE) -C conf generate + $(MAKE) -C man generate all_man: $(MAKE) -C man all_man diff --git a/man/Makefile.in b/man/Makefile.in index 6c799a5..e7020cd 100644 --- a/man/Makefile.in +++ b/man/Makefile.in @@ -1,6 +1,6 @@ # # Copyright (C) 2001-2004 Sistina Software, Inc. All rights reserved. -# Copyright (C) 2004-2011 Red Hat, Inc. All rights reserved. +# Copyright (C) 2004-2017 Red Hat, Inc. All rights reserved. # # This file is part of LVM2. # @@ -31,24 +31,20 @@ LVMRAIDMAN = lvmraid.7 MAN5=lvm.conf.5 MAN7=lvmsystemid.7 lvmreport.7 -MAN8=lvm.8 lvmconf.8 lvmdump.8 -MAN8DM=dmsetup.8 dmstats.8 -MAN8CLUSTER= -MAN8SYSTEMD_GENERATORS=lvm2-activation-generator.8 - -MAN8GEN=lvm-config.8 lvm-dumpconfig.8 lvm-fullreport.8 lvm-lvpoll.8 \ - lvcreate.8 lvchange.8 lvmconfig.8 lvconvert.8 lvdisplay.8 lvextend.8 \ - lvreduce.8 lvremove.8 lvrename.8 lvresize.8 lvs.8 \ - lvscan.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 vgmerge.8 vgmknodes.8 vgreduce.8 vgremove.8 \ - vgrename.8 vgs.8 vgscan.8 vgsplit.8 \ - lvmsar.8 lvmsadc.8 lvmdiskscan.8 lvmchange.8 +MAN8=lvm.8 lvmconf.8 lvmdump.8 lvm-config.8 lvm-dumpconfig.8 lvm-fullreport.8 \ + lvm-lvpoll.8 lvcreate.8 lvchange.8 lvmconfig.8 lvconvert.8 lvdisplay.8 \ + lvextend.8 lvreduce.8 lvremove.8 lvrename.8 lvresize.8 lvs.8 \ + lvscan.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 vgmerge.8 vgmknodes.8 vgreduce.8 vgremove.8 \ + vgrename.8 vgs.8 vgscan.8 vgsplit.8 \ + lvmsar.8 lvmsadc.8 lvmdiskscan.8 lvmchange.8 MAN8DM=dmsetup.8 dmstats.8 dmfilemapd.8 MAN8CLUSTER= MAN8SYSTEMD_GENERATORS=lvm2-activation-generator.8 + ifeq ($(MAKECMDGOALS),all_man) MAN_ALL="yes" endif @@ -116,46 +112,73 @@ MAN5DIR=$(mandir)/man5 MAN7DIR=$(mandir)/man7 MAN8DIR=$(mandir)/man8 +MANGENERATOR=man-generator +TESTMAN=test.gen + include $(top_builddir)/make.tmpl -CLEAN_TARGETS+=$(MAN5) $(MAN7) $(MAN8) $(MAN8GEN) $(MAN8CLUSTER) \ - $(MAN8SYSTEMD_GENERATORS) $(MAN8DM) *.gen man-generator +CLEAN_TARGETS+=$(MAN5) $(MAN7) $(MAN8) $(MAN8:%.8_gen=%.8) $(MAN8CLUSTER) \ + $(MAN8SYSTEMD_GENERATORS) $(MAN8DM) $(MANGENERATOR) $(TESTMAN) DISTCLEAN_TARGETS+=$(FSADMMAN) $(BLKDEACTIVATEMAN) $(DMEVENTDMAN) \ $(LVMETADMAN) $(LVMPOLLDMAN) $(LVMLOCKDMAN) $(CLVMDMAN) $(CMIRRORDMAN) \ $(LVMCACHEMAN) $(LVMTHINMAN) $(LVMDBUSDMAN) $(LVMRAIDMAN) all: man device-mapper -.PHONY: man install_man5 install_man7 install_man8 +.PHONY: man install_man5 install_man7 install_man8 pregenerated_man device-mapper: $(MAN8DM) -man: $(MAN5) $(MAN7) $(MAN8) $(MAN8GEN) $(MAN8CLUSTER) $(MAN8SYSTEMD_GENERATORS) +man: $(MAN5) $(MAN7) $(MAN8) $(MAN8CLUSTER) $(MAN8SYSTEMD_GENERATORS) all_man: man -$(MAN5) $(MAN7) $(MAN8) $(MAN8GEN) $(MAN8DM) $(MAN8CLUSTER): Makefile +$(MAN5) $(MAN7) $(MAN8) $(MAN8DM) $(MAN8CLUSTER) $(MAN8SYSTEMD_GENERATORS): Makefile -Makefile: Makefile.in - @: - -%: %.in - @case "$@" in \ - */*) ;; \ - *) echo "Creating $@" ; $(SED) -e "s+#VERSION#+$(LVM_VERSION)+;s+#DEFAULT_SYS_DIR#+$(DEFAULT_SYS_DIR)+;s+#DEFAULT_ARCHIVE_DIR#+$(DEFAULT_ARCHIVE_DIR)+;s+#DEFAULT_BACKUP_DIR#+$(DEFAULT_BACKUP_DIR)+;s+#DEFAULT_PROFILE_DIR#+$(DEFAULT_PROFILE_DIR)+;s+#DEFAULT_CACHE_DIR#+$(DEFAULT_CACHE_DIR)+;s+#DEFAULT_LOCK_DIR#+$(DEFAULT_LOCK_DIR)+;s+#CLVMD_PATH#+ at CLVMD_PATH@+;s+#LVM_PATH#+ at LVM_PATH@+;s+#DEFAULT_RUN_DIR#+ at DEFAULT_RUN_DIR@+;s+#DEFAULT_PID_DIR#+ at DEFAULT_PID_DIR@+;s+#SYSTEMD_GENERATOR_DIR#+$(SYSTEMD_GENERATOR_DIR)+;s+#DEFAULT_MANGLING#+$(DEFAULT_MANGLING)+;" $< > $@ ;; \ - esac - -man-generator: +$(MANGENERATOR): Makefile $(CC) -DMAN_PAGE_GENERATOR -I$(top_builddir)/tools $(CFLAGS) $(top_srcdir)/tools/command.c -o $@ - - ./man-generator --primary lvmconfig > test.gen - if [ ! -s test.gen ] ; then cp genfiles/*.gen $(top_builddir)/man; fi; -$(MAN8GEN): man-generator - echo "Generating $@" ; - if [ ! -e $@.gen ]; then ./man-generator --primary $(basename $@) $(top_srcdir)/man/$@.des > $@.gen; ./man-generator --secondary $(basename $@) >> $@.gen; fi - if [ -f $(top_srcdir)/man/$@.end ]; then cat $(top_srcdir)/man/$@.end >> $@.gen; fi; - cat $(top_srcdir)/man/see_also.end >> $@.gen - $(SED) -e "s+#VERSION#+$(LVM_VERSION)+;s+#DEFAULT_SYS_DIR#+$(DEFAULT_SYS_DIR)+;s+#DEFAULT_ARCHIVE_DIR#+$(DEFAULT_ARCHIVE_DIR)+;s+#DEFAULT_BACKUP_DIR#+$(DEFAULT_BACKUP_DIR)+;s+#DEFAULT_PROFILE_DIR#+$(DEFAULT_PROFILE_DIR)+;s+#DEFAULT_CACHE_DIR#+$(DEFAULT_CACHE_DIR)+;s+#DEFAULT_LOCK_DIR#+$(DEFAULT_LOCK_DIR)+;s+#CLVMD_PATH#+ at CLVMD_PATH@+;s+#LVM_PATH#+ at LVM_PATH@+;s+#DEFAULT_RUN_DIR#+ at DEFAULT_RUN_DIR@+;s+#DEFAULT_PID_DIR#+ at DEFAULT_PID_DIR@+;s+#SYSTEMD_GENERATOR_DIR#+$(SYSTEMD_GENERATOR_DIR)+;s+#DEFAULT_MANGLING#+$(DEFAULT_MANGLING)+;" $@.gen > $@ +# Test whether or not the man page generator works +$(TESTMAN): $(MANGENERATOR) + - $(MANGENERATOR) --primary lvmconfig > $@ + +SEE_ALSO=$(srcdir)/see_also.end + +%.8_gen: $(srcdir)/%.8_des $(srcdir)/%.8_end $(MANGENERATOR) $(TESTMAN) + ( \ + if [ ! -s $(TESTMAN) ] ; then \ + echo "Copying pre-generated $@" ; \ + else \ + echo "Generating $@" ; \ + fi \ + ) + ( \ + if [ ! -s $(TESTMAN) ] ; then \ + cat $(srcdir)/$(@:%.8_gen=%.8_pregen) ; \ + else \ + MANCMD=$(basename $@) && \ + $(MANGENERATOR) --primary $$MANCMD $< && \ + $(MANGENERATOR) --secondary $$MANCMD && \ + cat $(srcdir)/$(basename $@).8_end && \ + cat $(SEE_ALSO) ; \ + fi \ + ) > $@ + +define SUBSTVARS +echo "Generating $@" ; $(SED) -e "s+#VERSION#+$(LVM_VERSION)+;s+#DEFAULT_SYS_DIR#+$(DEFAULT_SYS_DIR)+;s+#DEFAULT_ARCHIVE_DIR#+$(DEFAULT_ARCHIVE_DIR)+;s+#DEFAULT_BACKUP_DIR#+$(DEFAULT_BACKUP_DIR)+;s+#DEFAULT_PROFILE_DIR#+$(DEFAULT_PROFILE_DIR)+;s+#DEFAULT_CACHE_DIR#+$(DEFAULT_CACHE_DIR)+;s+#DEFAULT_LOCK_DIR#+$(DEFAULT_LOCK_DIR)+;s+#CLVMD_PATH#+/data/lvmtest/usr/sbin/clvmd+;s+#LVM_PATH#+/data/lvmtest/sbin/lvm+;s+#DEFAULT_RUN_DIR#+/var/run/lvm+;s+#DEFAULT_PID_DIR#+/var/run+;s+#SYSTEMD_GENERATOR_DIR#+$(SYSTEMD_GENERATOR_DIR)+;s+#DEFAULT_MANGLING#+$(DEFAULT_MANGLING)+;" $< > $@ +endef + +%.5: $(srcdir)/%.5_main + $(SUBSTVARS) + +%.7: $(srcdir)/%.7_main + $(SUBSTVARS) + +%.8: $(srcdir)/%.8_main + $(SUBSTVARS) + +%.8: %.8_gen + $(SUBSTVARS) install_man5: $(MAN5) $(INSTALL) -d $(MAN5DIR) @@ -165,10 +188,10 @@ install_man7: $(MAN7) $(INSTALL) -d $(MAN7DIR) $(INSTALL_DATA) $(MAN7) $(MAN7DIR)/ -install_man8: $(MAN8) $(MAN8GEN) +install_man8: $(MAN8) $(MAN8GENERATED) $(INSTALL) -d $(MAN8DIR) $(INSTALL_DATA) $(MAN8) $(MAN8DIR)/ - $(INSTALL_DATA) $(MAN8GEN) $(MAN8DIR)/ + $(INSTALL_DATA) $(MAN8GENERATED) $(MAN8DIR)/ install_lvm2: install_man5 install_man7 install_man8 @@ -189,3 +212,12 @@ install_systemd_generators: $(MAN8SYSTEMD_GENERATORS) install: install_lvm2 install_device-mapper install_cluster install_all_man: install install_systemd_generators + +# Copy generated man pages back to source tree as fallback for machines where generator doesn't work +pregenerated_man: all + for i in $(srcdir)/*.8_des; do \ + CMD=`basename $$i .8_des`; \ + cat $${CMD}.8 > $(srcdir)/$$CMD.8_pregen ; \ + done + +generate: pregenerated_man diff --git a/man/blkdeactivate.8.in b/man/blkdeactivate.8.in deleted file mode 100644 index 8bb10b5..0000000 --- a/man/blkdeactivate.8.in +++ /dev/null @@ -1,105 +0,0 @@ -.TH "BLKDEACTIVATE" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" -.SH "NAME" -blkdeactivate \(em utility to deactivate block devices -.SH SYNOPSIS -.B blkdeactivate -.RB [ \-d \ \fIdm_options\fP ] -.RB [ \-e ] -.RB [ \-h ] -.RB [ \-l \ \fIlvm_options\fP ] -.RB [ \-m \ \fImpath_options\fP ] -.RB [ \-u ] -.RB [ \-v ] -.RI [ device ] -.SH DESCRIPTION -blkdeactivate utility deactivates block devices. If a device -is mounted, the utility can unmount it automatically before -trying to deactivate. The utility currently supports -device-mapper devices (DM), including LVM volumes and -software RAID MD devices. LVM volumes are handled directly -using the \fBlvm\fP(8) command, the rest of device-mapper -based devices are handled using the \fBdmsetup\fP(8) command. -MD devices are handled using the \fBmdadm\fP(8) command. -.SH OPTIONS -.TP -.BR \-d ", " \-\-dmoption \ \fIdm_options\fP -Comma separated list of device-mapper specific options. -Accepted \fBdmsetup\fP(8) options are: -.RS -.IP \fIretry\fP -Retry removal several times in case of failure. -.IP \fIforce\fP -Force device removal. -.RE -.TP -.BR \-e ", " \-\-errors -Show errors reported from tools called by \fBblkdeactivate\fP. Without this -option, any error messages from these external tools are suppressed and the -\fBblkdeactivate\fP itself provides only a summary message about device being -skipped or not. -.TP -.BR \-h ", " \-\-help -Display the help text. -.TP -.BR \-l ", " \-\-lvmoption \ \fIlvm_options\fP -Comma separated list of LVM specific options: -.RS -.IP \fIretry\fP -Retry removal several times in case of failure. -.IP \fIwholevg\fP -Deactivate the whole LVM Volume Group when processing a Logical Volume. -Deactivating Volume Group as a whole takes less time than deactivating each -Logical Volume separately. -.RE -.TP -.BR \-m ", " \-\-mpathoption \ \fImpath_options\fP -Comma separated list of device-mapper multipath specific options: -.RS -.IP \fIdisablequeueing\fP -Disable queueing on all multipath devices first before deactivation. -This avoids a situation where blkdeactivate may end up waiting if -all paths are unavailable for any underlying device-mapper multipath -device. -.RE -.TP -.BR \-u ", " \-\-umount -Unmount a mounted device before trying to deactivate it. -Without this option used, a device that is mounted is not deactivated. -.TP -.BR \-v ", " \-\-verbose -Run in verbose mode. Use \-\-vv for even more verbose mode. -.SH EXAMPLES -.sp -Deactivate all supported block devices found in the system. If a device -is mounted, skip its deactivation. -.sp -.B blkdeactivate - -Deactivate all supported block devices found in the system. If a device -is mounted, unmount it first if possible. -.sp -.B blkdeactivate \-u - -Deactivate supplied device together with all its holders. If any of the -devices processed is mounted, unmount it first if possible. -.sp -.B blkdeactivate \-u /dev/vg/lvol0 - -Deactivate all supported block devices found in the system. Retry deactivation -of device-mapper devices in case the deactivation fails. Deactivate the whole -Volume Group at once when processing an LVM Logical Volume. -.sp -.B blkdeactivate \-u \-d retry \-l wholevg - -Deactivate all supported block devices found in the system. Retry deactivation -of device-mapper devices in case the deactivation fails and force removal. -.sp -.B blkdeactivate \-d force,retry - -.SH SEE ALSO -.BR dmsetup (8), -.BR lsblk (8), -.BR lvm (8), -.BR mdadm (8), -.BR multipathd (8), -.BR umount (8) diff --git a/man/blkdeactivate.8_main b/man/blkdeactivate.8_main new file mode 100644 index 0000000..8bb10b5 --- /dev/null +++ b/man/blkdeactivate.8_main @@ -0,0 +1,105 @@ +.TH "BLKDEACTIVATE" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" +.SH "NAME" +blkdeactivate \(em utility to deactivate block devices +.SH SYNOPSIS +.B blkdeactivate +.RB [ \-d \ \fIdm_options\fP ] +.RB [ \-e ] +.RB [ \-h ] +.RB [ \-l \ \fIlvm_options\fP ] +.RB [ \-m \ \fImpath_options\fP ] +.RB [ \-u ] +.RB [ \-v ] +.RI [ device ] +.SH DESCRIPTION +blkdeactivate utility deactivates block devices. If a device +is mounted, the utility can unmount it automatically before +trying to deactivate. The utility currently supports +device-mapper devices (DM), including LVM volumes and +software RAID MD devices. LVM volumes are handled directly +using the \fBlvm\fP(8) command, the rest of device-mapper +based devices are handled using the \fBdmsetup\fP(8) command. +MD devices are handled using the \fBmdadm\fP(8) command. +.SH OPTIONS +.TP +.BR \-d ", " \-\-dmoption \ \fIdm_options\fP +Comma separated list of device-mapper specific options. +Accepted \fBdmsetup\fP(8) options are: +.RS +.IP \fIretry\fP +Retry removal several times in case of failure. +.IP \fIforce\fP +Force device removal. +.RE +.TP +.BR \-e ", " \-\-errors +Show errors reported from tools called by \fBblkdeactivate\fP. Without this +option, any error messages from these external tools are suppressed and the +\fBblkdeactivate\fP itself provides only a summary message about device being +skipped or not. +.TP +.BR \-h ", " \-\-help +Display the help text. +.TP +.BR \-l ", " \-\-lvmoption \ \fIlvm_options\fP +Comma separated list of LVM specific options: +.RS +.IP \fIretry\fP +Retry removal several times in case of failure. +.IP \fIwholevg\fP +Deactivate the whole LVM Volume Group when processing a Logical Volume. +Deactivating Volume Group as a whole takes less time than deactivating each +Logical Volume separately. +.RE +.TP +.BR \-m ", " \-\-mpathoption \ \fImpath_options\fP +Comma separated list of device-mapper multipath specific options: +.RS +.IP \fIdisablequeueing\fP +Disable queueing on all multipath devices first before deactivation. +This avoids a situation where blkdeactivate may end up waiting if +all paths are unavailable for any underlying device-mapper multipath +device. +.RE +.TP +.BR \-u ", " \-\-umount +Unmount a mounted device before trying to deactivate it. +Without this option used, a device that is mounted is not deactivated. +.TP +.BR \-v ", " \-\-verbose +Run in verbose mode. Use \-\-vv for even more verbose mode. +.SH EXAMPLES +.sp +Deactivate all supported block devices found in the system. If a device +is mounted, skip its deactivation. +.sp +.B blkdeactivate + +Deactivate all supported block devices found in the system. If a device +is mounted, unmount it first if possible. +.sp +.B blkdeactivate \-u + +Deactivate supplied device together with all its holders. If any of the +devices processed is mounted, unmount it first if possible. +.sp +.B blkdeactivate \-u /dev/vg/lvol0 + +Deactivate all supported block devices found in the system. Retry deactivation +of device-mapper devices in case the deactivation fails. Deactivate the whole +Volume Group at once when processing an LVM Logical Volume. +.sp +.B blkdeactivate \-u \-d retry \-l wholevg + +Deactivate all supported block devices found in the system. Retry deactivation +of device-mapper devices in case the deactivation fails and force removal. +.sp +.B blkdeactivate \-d force,retry + +.SH SEE ALSO +.BR dmsetup (8), +.BR lsblk (8), +.BR lvm (8), +.BR mdadm (8), +.BR multipathd (8), +.BR umount (8) diff --git a/man/clvmd.8.in b/man/clvmd.8.in deleted file mode 100644 index 21f8c7d..0000000 --- a/man/clvmd.8.in +++ /dev/null @@ -1,199 +0,0 @@ -.TH CLVMD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- -. -.SH NAME -. -clvmd \(em cluster LVM daemon -. -.SH SYNOPSIS -. -.ad l -.B clvmd -.RB [ \-C ] -.RB [ \-d -.RI [ value ]] -.RB [ \-E -.IR lock_uuid ] -.RB [ \-f ] -.RB [ \-h ] -.RB [ \-I -.IR cluster_manager ] -.RB [ \-R ] -.RB [ \-S ] -.RB [ \-t -.IR timeout ] -.RB [ \-T -.IR start_timeout ] -.RB [ \-V ] -.ad b -. -.SH DESCRIPTION -. -clvmd is the daemon that distributes LVM metadata updates around a cluster. -It must be running on all nodes in the cluster and will give an error -if a node in the cluster does not have this daemon running. -. -.SH OPTIONS -. -.HP -.BR \-C -.br -Only valid if \fB\-d\fP is also specified. -Tells all clvmds in a cluster to enable/disable debug logging. -Without this switch, only the local clvmd will change its debug level to that -given with \fB\-d\fP. -.br -This does not work correctly if specified on the command-line that starts clvmd. -If you want to start clvmd \fBand\fP -enable cluster-wide logging then the command needs to be issued twice, eg: -.br -.BR clvmd -.br -.BR clvmd\ \-d2 -. -.HP -.BR \-d -.RI [ value ] -.br -Set debug logging level. -If \fB\-d\fP is specified without a \fIvalue\fP -then 1 is assumed. \fIValue\fP can be: -.PD 0 -.IP -.BR 0 -\(em Disabled -.IP -.BR 1 -\(em Sends debug logs to stderr (implies \fB\-f\fP) -.IP -.BR 2 -\(em Sends debug logs to \fBsyslog\fP(3) -.PD -. -.HP -.BR \-E -.IR lock_uuid -.br -Pass lock uuid to be reacquired exclusively when clvmd is restarted. -. -.HP -.BR \-f -.br -Don't fork, run in the foreground. -. -.HP -.BR \-h -.br -Show help information. -. -.HP -.BR \-I -.IR cluster_manager -.br -Selects the cluster manager to use for locking and internal -communications. As it is quite possible to have multiple managers available on -the same system you might have to manually specify this option to override the -search. - -By default, omit \fB-I\fP is equivalent to \fB\-Iauto\fP. -Clvmd will use the first cluster manager that succeeds, -and it checks them in a predefined order -.BR cman , -.BR corosync , -.BR openais . -The available managers will be listed by order as part of the -\fBclvmd \-h\fP output. -. -.HP -.BR \-R -.br -Tells all the running instance of \fBclvmd\fP in the cluster to reload their device cache and -re-read the lvm configuration file \fBlvm.conf\fP(5). This command should be run whenever the -devices on a cluster system are changed. -. -.HP -.BR \-S -.br -Tells the running \fBclvmd\fP to exit and reexecute itself, for example at the -end of a package upgrade. The new instance is instructed to reacquire -any locks in the same state as they were previously held. (Alternative -methods of restarting the daemon have the side effect of changing -exclusive LV locks into shared locks.) -. -.HP -.BR \-t -.IR timeout -.br -Specifies the \fItimeout\fP for commands to run around the cluster. This should not -be so small that commands with many disk updates to do will fail, so you -may need to increase this on systems with very large disk farms. -The default is 60 seconds. -. -.HP -.BR \-T -.IR start_timeout -.br -Specifies the start timeout for \fBclvmd\fP daemon startup. If the -daemon does not report that it has started up within this time then the parent -command will exit with status of 5. This does NOT mean that \fBclvmd\fP has -not started! What it means is that the startup has been delayed for some -reason; the most likely cause of this is an inquorate cluster though it -could be due to locking latencies on a cluster with large numbers of logical -volumes. If you get the return code of 5 it is usually not necessary to -restart \fBclvmd\fP it will start as soon as that blockage has cleared. -This flag is to allow startup scripts to exit in a timely fashion even if the -cluster is stalled for some reason. - -The default is \fB0\fP (no timeout) and the value is in seconds. Don't set this too -small or you will experience spurious errors. 10 or 20 seconds might be -sensible. - -This timeout will be ignored if you start \fBclvmd\fP with the \fB\-d\fP. -. -.HP -.BR \-V -.br -Display the version of the cluster LVM daemon. -. -.SH NOTES -. -.SS Activation -. -In a clustered VG, clvmd is used for activation, and the following values are -possible with \fBlvchange/vgchange -a\fP: -.IP \fBy\fP|\fBsy\fP -clvmd activates the LV in shared mode (with a shared lock), -allowing multiple nodes to activate the LV concurrently. -If the LV type prohibits shared access, such as an LV with a snapshot, -an exclusive lock is automatically used instead. -clvmd attempts to activate the LV concurrently on all nodes. -.IP \fBey\fP -clvmd activates the LV in exclusive mode (with an exclusive lock), -allowing a single node to activate the LV. -clvmd attempts to activate the LV concurrently on all nodes, but only -one will succeed. -.IP \fBly\fP -clvmd attempts to activate the LV only on the local node. -If the LV type allows concurrent access, then shared mode is used, -otherwise exclusive. -.IP \fBn\fP -clvmd deactivates the LV on all nodes. -.IP \fBln\fP -clvmd deactivates the LV on the local node. -. -.SH ENVIRONMENT VARIABLES -.TP -.B LVM_CLVMD_BINARY -The CLVMD binary to use when \fBclvmd\fP restart is requested. -Defaults to \fI#CLVMD_PATH#\fP. -.TP -.B LVM_BINARY -The LVM2 binary to use. -Defaults to \fI#LVM_PATH#\fP. -.SH FILES -.I #CLVMD_PATH# -.br -.I #LVM_PATH# -.SH SEE ALSO -.BR syslog (3), -.BR lvm.conf (5), -.BR lvm (8) diff --git a/man/clvmd.8_main b/man/clvmd.8_main new file mode 100644 index 0000000..21f8c7d --- /dev/null +++ b/man/clvmd.8_main @@ -0,0 +1,199 @@ +.TH CLVMD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- +. +.SH NAME +. +clvmd \(em cluster LVM daemon +. +.SH SYNOPSIS +. +.ad l +.B clvmd +.RB [ \-C ] +.RB [ \-d +.RI [ value ]] +.RB [ \-E +.IR lock_uuid ] +.RB [ \-f ] +.RB [ \-h ] +.RB [ \-I +.IR cluster_manager ] +.RB [ \-R ] +.RB [ \-S ] +.RB [ \-t +.IR timeout ] +.RB [ \-T +.IR start_timeout ] +.RB [ \-V ] +.ad b +. +.SH DESCRIPTION +. +clvmd is the daemon that distributes LVM metadata updates around a cluster. +It must be running on all nodes in the cluster and will give an error +if a node in the cluster does not have this daemon running. +. +.SH OPTIONS +. +.HP +.BR \-C +.br +Only valid if \fB\-d\fP is also specified. +Tells all clvmds in a cluster to enable/disable debug logging. +Without this switch, only the local clvmd will change its debug level to that +given with \fB\-d\fP. +.br +This does not work correctly if specified on the command-line that starts clvmd. +If you want to start clvmd \fBand\fP +enable cluster-wide logging then the command needs to be issued twice, eg: +.br +.BR clvmd +.br +.BR clvmd\ \-d2 +. +.HP +.BR \-d +.RI [ value ] +.br +Set debug logging level. +If \fB\-d\fP is specified without a \fIvalue\fP +then 1 is assumed. \fIValue\fP can be: +.PD 0 +.IP +.BR 0 +\(em Disabled +.IP +.BR 1 +\(em Sends debug logs to stderr (implies \fB\-f\fP) +.IP +.BR 2 +\(em Sends debug logs to \fBsyslog\fP(3) +.PD +. +.HP +.BR \-E +.IR lock_uuid +.br +Pass lock uuid to be reacquired exclusively when clvmd is restarted. +. +.HP +.BR \-f +.br +Don't fork, run in the foreground. +. +.HP +.BR \-h +.br +Show help information. +. +.HP +.BR \-I +.IR cluster_manager +.br +Selects the cluster manager to use for locking and internal +communications. As it is quite possible to have multiple managers available on +the same system you might have to manually specify this option to override the +search. + +By default, omit \fB-I\fP is equivalent to \fB\-Iauto\fP. +Clvmd will use the first cluster manager that succeeds, +and it checks them in a predefined order +.BR cman , +.BR corosync , +.BR openais . +The available managers will be listed by order as part of the +\fBclvmd \-h\fP output. +. +.HP +.BR \-R +.br +Tells all the running instance of \fBclvmd\fP in the cluster to reload their device cache and +re-read the lvm configuration file \fBlvm.conf\fP(5). This command should be run whenever the +devices on a cluster system are changed. +. +.HP +.BR \-S +.br +Tells the running \fBclvmd\fP to exit and reexecute itself, for example at the +end of a package upgrade. The new instance is instructed to reacquire +any locks in the same state as they were previously held. (Alternative +methods of restarting the daemon have the side effect of changing +exclusive LV locks into shared locks.) +. +.HP +.BR \-t +.IR timeout +.br +Specifies the \fItimeout\fP for commands to run around the cluster. This should not +be so small that commands with many disk updates to do will fail, so you +may need to increase this on systems with very large disk farms. +The default is 60 seconds. +. +.HP +.BR \-T +.IR start_timeout +.br +Specifies the start timeout for \fBclvmd\fP daemon startup. If the +daemon does not report that it has started up within this time then the parent +command will exit with status of 5. This does NOT mean that \fBclvmd\fP has +not started! What it means is that the startup has been delayed for some +reason; the most likely cause of this is an inquorate cluster though it +could be due to locking latencies on a cluster with large numbers of logical +volumes. If you get the return code of 5 it is usually not necessary to +restart \fBclvmd\fP it will start as soon as that blockage has cleared. +This flag is to allow startup scripts to exit in a timely fashion even if the +cluster is stalled for some reason. + +The default is \fB0\fP (no timeout) and the value is in seconds. Don't set this too +small or you will experience spurious errors. 10 or 20 seconds might be +sensible. + +This timeout will be ignored if you start \fBclvmd\fP with the \fB\-d\fP. +. +.HP +.BR \-V +.br +Display the version of the cluster LVM daemon. +. +.SH NOTES +. +.SS Activation +. +In a clustered VG, clvmd is used for activation, and the following values are +possible with \fBlvchange/vgchange -a\fP: +.IP \fBy\fP|\fBsy\fP +clvmd activates the LV in shared mode (with a shared lock), +allowing multiple nodes to activate the LV concurrently. +If the LV type prohibits shared access, such as an LV with a snapshot, +an exclusive lock is automatically used instead. +clvmd attempts to activate the LV concurrently on all nodes. +.IP \fBey\fP +clvmd activates the LV in exclusive mode (with an exclusive lock), +allowing a single node to activate the LV. +clvmd attempts to activate the LV concurrently on all nodes, but only +one will succeed. +.IP \fBly\fP +clvmd attempts to activate the LV only on the local node. +If the LV type allows concurrent access, then shared mode is used, +otherwise exclusive. +.IP \fBn\fP +clvmd deactivates the LV on all nodes. +.IP \fBln\fP +clvmd deactivates the LV on the local node. +. +.SH ENVIRONMENT VARIABLES +.TP +.B LVM_CLVMD_BINARY +The CLVMD binary to use when \fBclvmd\fP restart is requested. +Defaults to \fI#CLVMD_PATH#\fP. +.TP +.B LVM_BINARY +The LVM2 binary to use. +Defaults to \fI#LVM_PATH#\fP. +.SH FILES +.I #CLVMD_PATH# +.br +.I #LVM_PATH# +.SH SEE ALSO +.BR syslog (3), +.BR lvm.conf (5), +.BR lvm (8) diff --git a/man/cmirrord.8.in b/man/cmirrord.8.in deleted file mode 100644 index ad604c7..0000000 --- a/man/cmirrord.8.in +++ /dev/null @@ -1,39 +0,0 @@ -.TH CMIRRORD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- -.SH NAME -cmirrord \(em cluster mirror log daemon - -.SH SYNOPSIS -\fBcmirrord\fR [\fB\-f\fR] [\fB\-h\fR] - -.SH DESCRIPTION -\fBcmirrord\fP is the daemon that tracks mirror log information in a cluster. -It is specific to device-mapper based mirrors (and by extension, LVM -cluster mirrors). Cluster mirrors are not possible without this daemon -running. - -This daemon relies on the cluster infrastructure provided by the -Cluster MANager (CMAN), which must be set up and running in order for -cmirrord to function. (The cluster infrastructure is also required for -\fBclvmd\fP(8).) - -Output is logged via \fBsyslog\fP(3). The \fBSIGUSR1 signal\fP(7) can be -issued to \fBcmirrord\fP to gather current status information for debugging -purposes. - -Once started, \fBcmirrord\fP will run until it is shutdown via \fBSIGINT\fP -signal. If there are still active cluster mirrors, however, the signal will be -ignored. Active cluster mirrors should be shutdown before stopping the cluster -mirror log daemon. - -.SH OPTIONS -.IP "\fB\-f\fR, \fB\-\-foreground\fR" 4 -Do not fork and log to the terminal. -.IP "\fB\-h\fR, \fB\-\-help\fR" 4 -Print usage. - -.SH SEE ALSO -.BR syslog (3), -.BR cluster.conf (5), -.BR signal (7), -.BR clvmd (8), -.BR lvm (8) diff --git a/man/cmirrord.8_main b/man/cmirrord.8_main new file mode 100644 index 0000000..ad604c7 --- /dev/null +++ b/man/cmirrord.8_main @@ -0,0 +1,39 @@ +.TH CMIRRORD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- +.SH NAME +cmirrord \(em cluster mirror log daemon + +.SH SYNOPSIS +\fBcmirrord\fR [\fB\-f\fR] [\fB\-h\fR] + +.SH DESCRIPTION +\fBcmirrord\fP is the daemon that tracks mirror log information in a cluster. +It is specific to device-mapper based mirrors (and by extension, LVM +cluster mirrors). Cluster mirrors are not possible without this daemon +running. + +This daemon relies on the cluster infrastructure provided by the +Cluster MANager (CMAN), which must be set up and running in order for +cmirrord to function. (The cluster infrastructure is also required for +\fBclvmd\fP(8).) + +Output is logged via \fBsyslog\fP(3). The \fBSIGUSR1 signal\fP(7) can be +issued to \fBcmirrord\fP to gather current status information for debugging +purposes. + +Once started, \fBcmirrord\fP will run until it is shutdown via \fBSIGINT\fP +signal. If there are still active cluster mirrors, however, the signal will be +ignored. Active cluster mirrors should be shutdown before stopping the cluster +mirror log daemon. + +.SH OPTIONS +.IP "\fB\-f\fR, \fB\-\-foreground\fR" 4 +Do not fork and log to the terminal. +.IP "\fB\-h\fR, \fB\-\-help\fR" 4 +Print usage. + +.SH SEE ALSO +.BR syslog (3), +.BR cluster.conf (5), +.BR signal (7), +.BR clvmd (8), +.BR lvm (8) diff --git a/man/dmeventd.8.in b/man/dmeventd.8.in deleted file mode 100644 index 057f756..0000000 --- a/man/dmeventd.8.in +++ /dev/null @@ -1,150 +0,0 @@ -.TH DMEVENTD 8 "DM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- -. -.SH NAME -. -dmeventd \(em Device-mapper event daemon -. -.SH SYNOPSIS -. -.B dmeventd -.RB [ \-d -.RB [ \-d -.RB [ \-d ]]] -.RB [ \-f ] -.RB [ \-h ] -.RB [ \-l ] -.RB [ \-R ] -.RB [ \-V ] -.RB [ \-? ] -. -.SH DESCRIPTION -. -dmeventd is the event monitoring daemon for device-mapper devices. -Library plugins can register and carry out actions triggered when -particular events occur. -. -. -.SH OPTIONS -. -.HP -.BR \-d -.br -Repeat from 1 to 3 times ( -.BR \-d , -.BR \-dd , -.BR \-ddd -) to increase the detail of -debug messages sent to syslog. -Each extra d adds more debugging information. -. -.HP -.BR \-f -.br -Don't fork, run in the foreground. -. -.HP -.BR \-h -.br -Show help information. -. -.HP -.BR \-l -.br -Log through stdout and stderr instead of syslog. -This option works only with option \-f, otherwise it is ignored. -. -.HP -.BR \-? -.br -Show help information on stderr. -. -.HP -.BR \-R -.br -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. -. -.HP -.BR \-V -.br -Show version of dmeventd. -. -.SH LVM PLUGINS -. -.HP -.BR Mirror -.br -Attempts to handle device failure automatically. See -.BR lvm.conf (5). -. -.HP -.BR Raid -.br -Attempts to handle device failure automatically. See -.BR lvm.conf (5). -. -.HP -.BR Snapshot -.br -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 -.BR lvm.conf (5). -Snapshot which runs out of space gets invalid and when it is mounted, -it gets umounted if possible. -. -.HP -.BR Thin -.br -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 -.BR lvm.conf (5). -When a thin pool fills over 50% (data or metadata) thin plugin calls -configured \fIdmeventd/thin_command\fP with every 5% increase. -With default setting it calls internal -\fBlvm lvextend --use-policies\fP to resize thin pool -when it's been filled above configured threshold -\fIactivation/thin_pool_autoextend_threshold\fP. -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 \fBfstrim\fP(8) to free recover space in a thin pool, -but also can use \fBlvextend --use-policies\fP if other actions -have not released enough space. -Command is executed with environmental variable -\fBLVM_RUN_BY_DMEVENTD=1\fP 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 -\fBDMEVENTD_THIN_POOL_DATA\fP and \fBDMEVENTD_THIN_POOL_DATA\fP. -Command can also read status with tools like \fBlvs\fP(8). -. -.SH ENVIRONMENT VARIABLES -. -.TP -.B 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. -.TP -.B DMEVENTD_THIN_POOL_DATA -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. -.TP -.B LVM_RUN_BY_DMEVENTD -Variable is set by thin plugin to prohibit recursive interation -with dmeventd by any executed lvm2 command from -a thin_command environment. -. -.SH SEE ALSO -. -.BR lvm (8), -.BR lvm.conf (5) diff --git a/man/dmeventd.8_main b/man/dmeventd.8_main new file mode 100644 index 0000000..057f756 --- /dev/null +++ b/man/dmeventd.8_main @@ -0,0 +1,150 @@ +.TH DMEVENTD 8 "DM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- +. +.SH NAME +. +dmeventd \(em Device-mapper event daemon +. +.SH SYNOPSIS +. +.B dmeventd +.RB [ \-d +.RB [ \-d +.RB [ \-d ]]] +.RB [ \-f ] +.RB [ \-h ] +.RB [ \-l ] +.RB [ \-R ] +.RB [ \-V ] +.RB [ \-? ] +. +.SH DESCRIPTION +. +dmeventd is the event monitoring daemon for device-mapper devices. +Library plugins can register and carry out actions triggered when +particular events occur. +. +. +.SH OPTIONS +. +.HP +.BR \-d +.br +Repeat from 1 to 3 times ( +.BR \-d , +.BR \-dd , +.BR \-ddd +) to increase the detail of +debug messages sent to syslog. +Each extra d adds more debugging information. +. +.HP +.BR \-f +.br +Don't fork, run in the foreground. +. +.HP +.BR \-h +.br +Show help information. +. +.HP +.BR \-l +.br +Log through stdout and stderr instead of syslog. +This option works only with option \-f, otherwise it is ignored. +. +.HP +.BR \-? +.br +Show help information on stderr. +. +.HP +.BR \-R +.br +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. +. +.HP +.BR \-V +.br +Show version of dmeventd. +. +.SH LVM PLUGINS +. +.HP +.BR Mirror +.br +Attempts to handle device failure automatically. See +.BR lvm.conf (5). +. +.HP +.BR Raid +.br +Attempts to handle device failure automatically. See +.BR lvm.conf (5). +. +.HP +.BR Snapshot +.br +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 +.BR lvm.conf (5). +Snapshot which runs out of space gets invalid and when it is mounted, +it gets umounted if possible. +. +.HP +.BR Thin +.br +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 +.BR lvm.conf (5). +When a thin pool fills over 50% (data or metadata) thin plugin calls +configured \fIdmeventd/thin_command\fP with every 5% increase. +With default setting it calls internal +\fBlvm lvextend --use-policies\fP to resize thin pool +when it's been filled above configured threshold +\fIactivation/thin_pool_autoextend_threshold\fP. +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 \fBfstrim\fP(8) to free recover space in a thin pool, +but also can use \fBlvextend --use-policies\fP if other actions +have not released enough space. +Command is executed with environmental variable +\fBLVM_RUN_BY_DMEVENTD=1\fP 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 +\fBDMEVENTD_THIN_POOL_DATA\fP and \fBDMEVENTD_THIN_POOL_DATA\fP. +Command can also read status with tools like \fBlvs\fP(8). +. +.SH ENVIRONMENT VARIABLES +. +.TP +.B 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. +.TP +.B DMEVENTD_THIN_POOL_DATA +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. +.TP +.B LVM_RUN_BY_DMEVENTD +Variable is set by thin plugin to prohibit recursive interation +with dmeventd by any executed lvm2 command from +a thin_command environment. +. +.SH SEE ALSO +. +.BR lvm (8), +.BR lvm.conf (5) diff --git a/man/dmfilemapd.8.in b/man/dmfilemapd.8.in deleted file mode 100644 index 8e19e4b..0000000 --- a/man/dmfilemapd.8.in +++ /dev/null @@ -1,212 +0,0 @@ -.TH DMFILEMAPD 8 "Dec 17 2016" "Linux" "MAINTENANCE COMMANDS" - -.de OPT_FD -. RB [ file_descriptor ] -.. -. -.de OPT_GROUP -. RB [ group_id ] -.. -.de OPT_PATH -. RB [ abs_path ] -.. -. -.de OPT_MODE -. RB [ mode ] -.. -. -.de OPT_DEBUG -. RB [ foreground [ verbose ] ] -.. -. -.SH NAME -. -dmfilemapd \(em device-mapper filemap monitoring daemon -. -.SH SYNOPSIS -. -.de CMD_DMFILEMAPD -. ad l -. IR dmfilemapd -. OPT_FD -. OPT_GROUP -. OPT_PATH -. OPT_MODE -. OPT_DEBUG -. ad b -.. -.CMD_DMFILEMAPD -. -.PD -.ad b -. -.SH DESCRIPTION -. -The dmfilemapd daemon monitors groups of \fIdmstats\fP 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 \fPdmstats -create\fP 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. -. -.SH OPTIONS -. -.HP -.BR file_descriptor -.br -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 \fBdmfilemapd\fP is responsible for -opening the file descriptor that is handed to the daemon. -. -.HP -.BR group_id -.br -The \fBdmstats\fP group identifier of the group that \fBdmfilemapd\fP -should update. The group must exist and it should correspond to -a set of regions created by a previous filemap operation. -. -.HP -.BR abs_path -.br -The absolute path to the file being monitored, at the time that -it was opened. The use of \fBpath\fP by the daemon differs, -depending on the filemap following mode in use; see \fBMODES\fP -and the \fBmode\fP option for more information. - -.br -.HP -.BR mode -.br -The filemap monitoring mode the daemon should use: either "inode" -(\fBDM_FILEMAP_FOLLOW_INODE\fP), or "path" -(\fBDM_FILEMAP_FOLLOW_PATH\fP), to enable follow-inode or -follow-path mode respectively. -. -.HP -.BR [foreground] -.br -If set to 1, disable forking and allow the daemon to run in the -foreground. -. -.HP -.BR [verbose] -Control daemon logging. If set to zero, the daemon will close all -stdio streams and run silently. If \fBverbose\fP 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. -. -. -.SH 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. - -.P -.B Follow inode -.P -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. - -.P -.B Follow path -.P -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. -. -.SH 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 \fBdd\fP program). - -There is a further loss of events in that there is currently no way -to atomically resize a \fBdmstats\fP 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. -. -.SH EXAMPLES -. -Normally the daemon is started automatically by the \fBdmstats\fP -\fBcreate\fP or \fBupdate_filemap\fP commands but it can be run -manually for debugging or testing purposes. -.P -Start the daemon in the background, in follow-path mode -.br -# -.B dmfilemapd 3 0 /srv/images/vm.img path 0 0 3< /srv/images/vm.img -.br -.P -Start the daemon in follow-inode mode, disable forking and enable -verbose logging -.br -# -.B dmfilemapd 3 0 /var/tmp/data inode 1 3 3< /var/tmp/data -.br -Starting dmfilemapd with fd=3, group_id=0 mode=inode, path=/var/tmp/data -.br -dm version [ opencount flush ] [16384] (*1) -.br -dm info (253:0) [ opencount flush ] [16384] (*1) -.br -dm message (253:0) [ opencount flush ] @stats_list dmstats [16384] (*1) -.br -Read alias 'data' from aux_data -.br -Found group_id 0: alias="data" -.br -dm_stats_walk_init: initialised flags to 4000000000000 -.br -starting stats walk with GROUP -.br -exiting _filemap_monitor_get_events() with deleted=0, check=0 -.br -Waiting for check interval -.br -.P -. -.SH AUTHORS -. -Bryn M. Reeves -. -.SH SEE ALSO -. -.BR dmstats (8) - -LVM2 resource page: https://www.sourceware.org/lvm2/ -.br -Device-mapper resource page: http://sources.redhat.com/dm/ -.br diff --git a/man/dmfilemapd.8_main b/man/dmfilemapd.8_main new file mode 100644 index 0000000..8e19e4b --- /dev/null +++ b/man/dmfilemapd.8_main @@ -0,0 +1,212 @@ +.TH DMFILEMAPD 8 "Dec 17 2016" "Linux" "MAINTENANCE COMMANDS" + +.de OPT_FD +. RB [ file_descriptor ] +.. +. +.de OPT_GROUP +. RB [ group_id ] +.. +.de OPT_PATH +. RB [ abs_path ] +.. +. +.de OPT_MODE +. RB [ mode ] +.. +. +.de OPT_DEBUG +. RB [ foreground [ verbose ] ] +.. +. +.SH NAME +. +dmfilemapd \(em device-mapper filemap monitoring daemon +. +.SH SYNOPSIS +. +.de CMD_DMFILEMAPD +. ad l +. IR dmfilemapd +. OPT_FD +. OPT_GROUP +. OPT_PATH +. OPT_MODE +. OPT_DEBUG +. ad b +.. +.CMD_DMFILEMAPD +. +.PD +.ad b +. +.SH DESCRIPTION +. +The dmfilemapd daemon monitors groups of \fIdmstats\fP 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 \fPdmstats +create\fP 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. +. +.SH OPTIONS +. +.HP +.BR file_descriptor +.br +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 \fBdmfilemapd\fP is responsible for +opening the file descriptor that is handed to the daemon. +. +.HP +.BR group_id +.br +The \fBdmstats\fP group identifier of the group that \fBdmfilemapd\fP +should update. The group must exist and it should correspond to +a set of regions created by a previous filemap operation. +. +.HP +.BR abs_path +.br +The absolute path to the file being monitored, at the time that +it was opened. The use of \fBpath\fP by the daemon differs, +depending on the filemap following mode in use; see \fBMODES\fP +and the \fBmode\fP option for more information. + +.br +.HP +.BR mode +.br +The filemap monitoring mode the daemon should use: either "inode" +(\fBDM_FILEMAP_FOLLOW_INODE\fP), or "path" +(\fBDM_FILEMAP_FOLLOW_PATH\fP), to enable follow-inode or +follow-path mode respectively. +. +.HP +.BR [foreground] +.br +If set to 1, disable forking and allow the daemon to run in the +foreground. +. +.HP +.BR [verbose] +Control daemon logging. If set to zero, the daemon will close all +stdio streams and run silently. If \fBverbose\fP 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. +. +. +.SH 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. + +.P +.B Follow inode +.P +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. + +.P +.B Follow path +.P +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. +. +.SH 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 \fBdd\fP program). + +There is a further loss of events in that there is currently no way +to atomically resize a \fBdmstats\fP 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. +. +.SH EXAMPLES +. +Normally the daemon is started automatically by the \fBdmstats\fP +\fBcreate\fP or \fBupdate_filemap\fP commands but it can be run +manually for debugging or testing purposes. +.P +Start the daemon in the background, in follow-path mode +.br +# +.B dmfilemapd 3 0 /srv/images/vm.img path 0 0 3< /srv/images/vm.img +.br +.P +Start the daemon in follow-inode mode, disable forking and enable +verbose logging +.br +# +.B dmfilemapd 3 0 /var/tmp/data inode 1 3 3< /var/tmp/data +.br +Starting dmfilemapd with fd=3, group_id=0 mode=inode, path=/var/tmp/data +.br +dm version [ opencount flush ] [16384] (*1) +.br +dm info (253:0) [ opencount flush ] [16384] (*1) +.br +dm message (253:0) [ opencount flush ] @stats_list dmstats [16384] (*1) +.br +Read alias 'data' from aux_data +.br +Found group_id 0: alias="data" +.br +dm_stats_walk_init: initialised flags to 4000000000000 +.br +starting stats walk with GROUP +.br +exiting _filemap_monitor_get_events() with deleted=0, check=0 +.br +Waiting for check interval +.br +.P +. +.SH AUTHORS +. +Bryn M. Reeves +. +.SH SEE ALSO +. +.BR dmstats (8) + +LVM2 resource page: https://www.sourceware.org/lvm2/ +.br +Device-mapper resource page: http://sources.redhat.com/dm/ +.br diff --git a/man/dmsetup.8.in b/man/dmsetup.8.in deleted file mode 100644 index 4261fc4..0000000 --- a/man/dmsetup.8.in +++ /dev/null @@ -1,1026 +0,0 @@ -.TH DMSETUP 8 "Apr 06 2006" "Linux" "MAINTENANCE COMMANDS" -. -.SH NAME -. -dmsetup \(em low level logical volume management -. -.SH SYNOPSIS -. -.\".nh -.ad l -.PD 0 -.HP 9 -.B dmsetup -.de CMD_CLEAR -. BR clear -. IR device_name -.. -.CMD_CLEAR -. -.HP -.B dmsetup -.de CMD_CREATE -. ad l -. BR create -. IR device_name -. RB [ -u | \-\-uuid -. IR uuid ] -. RB \%[ \-\-addnodeoncreate | \-\-addnodeonresume ] -. RB \%[ \-n | \-\-notable | \-\-table -. IR \%table | table_file ] -. RB [ \-\-readahead -. RB \%[ + ] \fIsectors | auto | none ] -. ad b -.. -.CMD_CREATE -. -.HP -.B dmsetup -.de CMD_DEPS -. ad l -. BR deps -. RB [ \-o -. IR options ] -. RI [ device_name ...] -. ad b -.. -.CMD_DEPS -. -.HP -.B dmsetup -.de CMD_HELP -. BR help -. RB [ \-c | \-C | \-\-columns ] -.. -.CMD_HELP -. -.HP -.B dmsetup -.de CMD_INFO -. BR info -. RI [ device_name ...] -.. -.CMD_INFO -. -.HP -.B dmsetup -.de CMD_INFOLONG -. ad l -. BR info -. BR \-c | \-C | \-\-columns -. RB [ \-\-count -. IR count ] -. RB [ \-\-interval -. IR seconds ] -. RB \%[ \-\-nameprefixes ] -. RB \%[ \-\-noheadings ] -. RB [ \-o -. IR fields ] -. RB [ \-O | \-\-sort -. IR sort_fields ] -. RB [ \-\-separator -. IR separator ] -. RI [ device_name ] -. ad b -.. -.CMD_INFOLONG -. -.HP -.B dmsetup -.de CMD_LOAD -. ad l -. BR load -. IR device_name -. RB [ \-\-table -. IR table | table_file ] -. ad b -.. -.CMD_LOAD -. -.HP -.B dmsetup -.de CMD_LS -. ad l -. BR ls -. RB [ \-\-target -. IR target_type ] -. RB [ \-\-exec -. IR command ] -. RB [ \-\-tree ] -. RB [ \-o -. IR options ] -. ad b -.. -.CMD_LS -. -.HP -.B dmsetup -.de CMD_MANGLE -. BR mangle -. RI [ device_name ...] -.. -.CMD_MANGLE -. -.HP -.B dmsetup -.de CMD_MESSAGE -. BR message -. IR device_name -. IR sector -. IR message -.. -.CMD_MESSAGE -. -.HP -.B dmsetup -.de CMD_MKNODES -. BR mknodes -. RI [ device_name ...] -.. -.CMD_MKNODES -. -.HP -.B dmsetup -.de CMD_RELOAD -. ad l -. BR reload -. IR device_name -. RB [ \-\-table -. IR table | table_file ] -. ad b -.. -.CMD_RELOAD -. -.HP -.B dmsetup -.de CMD_REMOVE -. ad l -. BR remove -. RB [ \-f | \-\-force ] -. RB [ \-\-retry ] -. RB [ \-\-deferred ] -. IR device_name ... -. ad b -.. -.CMD_REMOVE -. -.HP -.B dmsetup -.de CMD_REMOVE_ALL -. BR remove_all -. RB [ \-f | \-\-force ] -. RB [ \-\-deferred ] -.. -.CMD_REMOVE_ALL -. -.HP -.B dmsetup -.de CMD_RENAME -. BR rename -. IR device_name -. IR new_name -.. -.CMD_RENAME -. -.HP -.B dmsetup -.de CMD_RENAME_UUID -. BR rename -. IR device_name -. BR \-\-setuuid -. IR uuid -.. -.CMD_RENAME_UUID -. -.HP -.B dmsetup -.de CMD_RESUME -. ad l -. BR resume -. IR device_name ... -. RB [ \-\-addnodeoncreate | \-\-addnodeonresume ] -. RB [ \-\-noflush ] -. RB [ \-\-nolockfs ] -. RB \%[ \-\-readahead -. RB \%[ + ] \fIsectors | auto | none ] -. ad b -.. -.CMD_RESUME -. -.HP -.B dmsetup -.de CMD_SETGEOMETRY -. ad l -. BR setgeometry -. IR device_name -. IR cyl -. IR head -. IR sect -. IR start -. ad b -.. -.CMD_SETGEOMETRY -. -.HP -.B dmsetup -.de CMD_SPLITNAME -. BR splitname -. IR device_name -. RI [ subsystem ] -.. -.CMD_SPLITNAME -. -.HP -.B dmsetup -.de CMD_STATS -. BR stats -. IR command -. RI [ options ] -.. -.CMD_STATS -. -.HP -.B dmsetup -.de CMD_STATUS -. ad l -. BR status -. RB [ \-\-target -. IR target_type ] -. RB [ \-\-noflush ] -. RI [ device_name ...] -. ad b -.. -.CMD_STATUS -. -.HP -.B dmsetup -.de CMD_SUSPEND -. ad l -. BR suspend -. RB [ \-\-nolockfs ] -. RB [ \-\-noflush ] -. IR device_name ... -. ad b -.. -.CMD_SUSPEND -. -.HP -.B dmsetup -.de CMD_TABLE -. ad l -. BR table -. RB [ \-\-target -. IR target_type ] -. RB [ \-\-showkeys ] -. RI [ device_name ...] -. ad b -.. -.CMD_TABLE -. -.HP -.B dmsetup -.de CMD_TARGETS -. BR targets -.. -.CMD_TARGETS -. -.HP -.B dmsetup -.de CMD_UDEVCOMPLETE -. BR udevcomplete -. IR cookie -.. -.CMD_UDEVCOMPLETE -. -.HP -.B dmsetup -.de CMD_UDEVCOMPLETE_ALL -. BR udevcomplete_all -. RI [ age_in_minutes ] -.. -.CMD_UDEVCOMPLETE_ALL -. -.HP -.B dmsetup -.de CMD_UDEVCOOKIES -. BR udevcookie -.. -.CMD_UDEVCOOKIES -. -.HP -.B dmsetup -.de CMD_UDEVCREATECOOKIE -. BR udevcreatecookie -.. -.CMD_UDEVCREATECOOKIE -. -.HP -.B dmsetup -.de CMD_UDEVFLAGS -. BR udevflags -. IR cookie -.. -.CMD_UDEVFLAGS -. -.HP -.B dmsetup -.de CMD_UDEVRELEASECOOKIE -. BR udevreleasecookie -. RI [ cookie ] -.. -.CMD_UDEVRELEASECOOKIE -. -.HP -.B dmsetup -.de CMD_VERSION -. BR version -.. -.CMD_VERSION -. -.HP -.B dmsetup -.de CMD_WAIT -. ad l -. BR wait -. RB [ \-\-noflush ] -. IR device_name -. RI [ event_nr ] -. ad b -.. -.CMD_WAIT -. -.HP -.B dmsetup -.de CMD_WIPE_TABLE -. ad l -. BR wipe_table -. IR device_name ... -. RB [ \-f | \-\-force ] -. RB [ \-\-noflush ] -. RB [ \-\-nolockfs ] -. ad b -.. -.CMD_WIPE_TABLE -.PD -.P -.HP -.PD 0 -.B devmap_name \fImajor minor -.HP -.B devmap_name \fImajor:minor -.PD -.ad b -. -.SH DESCRIPTION -. -dmsetup manages logical devices that use the device-mapper driver. -Devices are created by loading a table that specifies a target for -each sector (512 bytes) in the logical device. - -The first argument to dmsetup is a command. -The second argument is the logical device name or uuid. - -Invoking the dmsetup tool as \fBdevmap_name\fP -(which is not normally distributed and is supported -only for historical reasons) is equivalent to -.BI \%dmsetup\ info\ \-c\ \-\-noheadings\ \-j \ major\ \-m \ minor \c -\fR. -.\" dot above here fixes -Thtml rendering for next HP option -. -.SH OPTIONS -. -.HP -.BR \-\-addnodeoncreate -.br -Ensure \fI/dev/mapper\fP node exists after \fBdmsetup create\fP. -. -.HP -.BR \-\-addnodeonresume -.br -Ensure \fI/dev/mapper\fP node exists after \fBdmsetup resume\fP (default with udev). -. -.HP -.BR \-\-checks -.br -Perform additional checks on the operations requested and report -potential problems. Useful when debugging scripts. -In some cases these checks may slow down operations noticeably. -. -.HP -.BR \-c | \-C | \-\-columns -.br -Display output in columns rather than as Field: Value lines. -. -.HP -.BR \-\-count -.IR count -.br -Specify the number of times to repeat a report. Set this to zero -continue until interrupted. The default interval is one second. -. -.HP -.BR \-f | \-\-force -.br -Try harder to complete operation. -. -.HP -.BR \-h | \-\-help -.br -Outputs a summary of the commands available, optionally including -the list of report fields (synonym with \fBhelp\fP command). -. -.HP -.BR \-\-inactive -.br -When returning any table information from the kernel report on the -inactive table instead of the live table. -Requires kernel driver version 4.16.0 or above. -. -.HP -.BR \-\-interval -.IR seconds -.br -Specify the interval in seconds between successive iterations for -repeating reports. If \fB\-\-interval\fP is specified but \fB\-\-count\fP -is not, reports will continue to repeat until interrupted. -The default interval is one second. -. -.HP -.BR \-\-manglename -.BR auto | hex | none -.br -Mangle any character not on a whitelist using mangling_mode when -processing device-mapper device names and UUIDs. The names and UUIDs -are mangled on input and unmangled on output where the mangling mode -is one of: -\fBauto\fP (only do the mangling if not mangled yet, do nothing -if already mangled, error on mixed), -\fBhex\fP (always do the mangling) and -\fBnone\fP (no mangling). -Default mode is \fB#DEFAULT_MANGLING#\fP. -Character whitelist: 0-9, A-Z, a-z, #+-.:=@_. This whitelist is -also supported by udev. Any character not on a whitelist is replaced -with its hex value (two digits) prefixed by \\x. -Mangling mode could be also set through -\fBDM_DEFAULT_NAME_MANGLING_MODE\fP -environment variable. -. -.HP -.BR \-j | \-\-major -.IR major -.br -Specify the major number. -. -.HP -.BR \-m | \-\-minor -.IR minor -.br -Specify the minor number. -. -.HP -.BR \-n | \-\-notable -.br -When creating a device, don't load any table. -. -.HP -.BR \-\-nameprefixes -.br -Add a "DM_" prefix plus the field name to the output. Useful with -\fB\-\-noheadings\fP to produce a list of -field=value pairs that can be used to set environment variables -(for example, in -.BR udev (7) -rules). -. -.HP -.BR \-\-noheadings -Suppress the headings line when using columnar output. -. -.HP -.BR \-\-noflush -Do not flush outstading I/O when suspending a device, or do not -commit thin-pool metadata when obtaining thin-pool status. -. -.HP -.BR \-\-nolockfs -.br -Do not attempt to synchronize filesystem eg, when suspending a device. -. -.HP -.BR \-\-noopencount -.br -Tell the kernel not to supply the open reference count for the device. -. -.HP -.BR \-\-noudevrules -.br -Do not allow udev to manage nodes for devices in device-mapper directory. -. -.HP -.BR \-\-noudevsync -.br -Do not synchronise with udev when creating, renaming or removing devices. -. -.HP -.BR \-o | \-\-options -.IR options -.br -Specify which fields to display. -. -.HP -.BR \-\-readahead -.RB [ + ] \fIsectors | auto | none -.br -Specify read ahead size in units of sectors. -The default value is \fBauto\fP which allows the kernel to choose -a suitable value automatically. The \fB+\fP prefix lets you -specify a minimum value which will not be used if it is -smaller than the value chosen by the kernel. -The value \fBnone\fP is equivalent to specifying zero. -. -.HP -.BR \-r | \-\-readonly -.br -Set the table being loaded read-only. -. -.HP -.BR \-S | \-\-select -.IR selection -.br -Display only rows that match \fIselection\fP criteria. All rows are displayed -with the additional "selected" column (\fB-o selected\fP) showing 1 if the row -matches the \fIselection\fP and 0 otherwise. The selection criteria are defined -by specifying column names and their valid values while making use of -supported comparison operators. As a quick help and to see full list of -column names that can be used in selection and the set of supported -selection operators, check the output of \fBdmsetup\ info\ -c\ -S\ help\fP -command. -. -.HP -.BR \-\-table -.IR table -.br -Specify a one-line table directly on the command line. -See below for more information on the table format. -. -.HP -.BR \-\-udevcookie -.IR cookie -.br -Use cookie for udev synchronisation. -Note: Same cookie should be used for same type of operations i.e. creation of -multiple different devices. It's not adviced to combine different -operations on the single device. -. -.HP -.BR \-u | \-\-uuid -.br -Specify the \fIuuid\fP. -. -.HP -.BR \-y | \-\-yes -.br -Answer yes to all prompts automatically. -. -.HP -.BR \-v | \-\-verbose -.RB [ \-v | \-\-verbose ] -.br -Produce additional output. -. -.HP -.BR \-\-verifyudev -.br -If udev synchronisation is enabled, verify that udev operations get performed -correctly and try to fix up the device nodes afterwards if not. -. -.HP -.BR \-\-version -.br -Display the library and kernel driver version. -.br -. -.SH COMMANDS -. -.HP -.CMD_CLEAR -.br -Destroys the table in the inactive table slot for device_name. -. -.HP -.CMD_CREATE -.br -Creates a device with the given name. -If \fItable\fP or \fItable_file\fP is supplied, the table is loaded and made live. -Otherwise a table is read from standard input unless \fB\-\-notable\fP is used. -The optional \fIuuid\fP can be used in place of -device_name in subsequent dmsetup commands. -If successful the device will appear in table and for live -device the node \fI/dev/mapper/device_name\fP is created. -See below for more information on the table format. -. -.HP -.CMD_DEPS -.br -Outputs a list of devices referenced by the live table for the specified -device. Device names on output can be customised by following \fIoptions\fP: -\fBdevno\fP (major and minor pair, used by default), -\fBblkdevname\fP (block device name), -\fBdevname\fP (map name for device-mapper devices, equal to blkdevname otherwise). -. -.HP -.CMD_HELP -.br -Outputs a summary of the commands available, optionally including -the list of report fields. -. -.HP -.CMD_INFO -.br -Outputs some brief information about the device in the form: -.RS -.RS - State: SUSPENDED|ACTIVE, READ-ONLY - Tables present: LIVE and/or INACTIVE - Open reference count - Last event sequence number (used by \fBwait\fP) - Major and minor device number - Number of targets in the live table - UUID -.RE -.RE -.HP -.CMD_INFOLONG -.br -Output you can customise. -Fields are comma-separated and chosen from the following list: -.BR name , -.BR major , -.BR minor , -.BR attr , -.BR open , -.BR segments , -.BR events , -.BR uuid . -Attributes are: -.RI ( L )ive, -.RI ( I )nactive, -.RI ( s )uspended, -.RI ( r )ead-only, -.RI read-( w )rite. -Precede the list with '\fB+\fP' to append -to the default selection of columns instead of replacing it. -Precede any sort field with '\fB-\fP' for a reverse sort on that column. -. -.HP -.CMD_LS -.br -List device names. Optionally only list devices that have at least -one target of the specified type. Optionally execute a command for -each device. The device name is appended to the supplied command. -Device names on output can be customised by following options: -\fBdevno\fP (major and minor pair, used by default), -\fBblkdevname\fP (block device name), -\fBdevname\fP (map name for device-mapper devices, equal to blkdevname otherwise). -\fB\-\-tree\fP displays dependencies between devices as a tree. -It accepts a comma-separate list of \fIoptions\fP. -Some specify the information displayed against each node: -.BR device / nodevice ; -.BR blkdevname ; -.BR active ", " open ", " rw ", " uuid . -Others specify how the tree is displayed: -.BR ascii ", " utf ", " vt100 ; -.BR compact ", " inverted ", " notrunc . -. -.HP -.BR load | \c -.CMD_RELOAD -.br -Loads \fItable\fP or \fItable_file\fP into the inactive table slot for device_name. -If neither is supplied, reads a table from standard input. -. -.HP -.CMD_MANGLE -.br -Ensure existing device-mapper \fIdevice_name\fP and UUID is in the correct mangled -form containing only whitelisted characters (supported by udev) and do -a rename if necessary. Any character not on the whitelist will be mangled -based on the \fB\-\-manglename\fP setting. Automatic rename works only for device -names and not for device UUIDs because the kernel does not allow changing -the UUID of active devices. Any incorrect UUIDs are reported only and they -must be manually corrected by deactivating the device first and then -reactivating it with proper mangling mode used (see also \fB\-\-manglename\fP). -. -.HP -.CMD_MESSAGE -.br -Send message to target. If sector not needed use 0. -. -.HP -.CMD_MKNODES -.br -Ensure that the node in \fI/dev/mapper\fP for \fIdevice_name\fP is correct. -If no device_name is supplied, ensure that all nodes in \fI/dev/mapper\fP -correspond to mapped devices currently loaded by the device-mapper kernel -driver, adding, changing or removing nodes as necessary. -. -.HP -.CMD_REMOVE -.br -Removes a device. It will no longer be visible to dmsetup. Open devices -cannot be removed, but adding \fB\-\-force\fP will replace the table with one -that fails all I/O. \fB\-\-deferred\fP will enable deferred removal of open -devices - the device will be removed when the last user closes it. The deferred -removal feature is supported since version 4.27.0 of the device-mapper -driver available in upstream kernel version 3.13. (Use \fBdmsetup version\fP -to check this.) If an attempt to remove a device fails, perhaps because a process run -from a quick udev rule temporarily opened the device, the \fB\-\-retry\fP -option will cause the operation to be retried for a few seconds before failing. -Do NOT combine -\fB\-\-force\fP and \fB\-\-udevcookie\fP, as udev may start to process udev -rules in the middle of error target replacement and result in nondeterministic -result. -. -.HP -.CMD_REMOVE_ALL -.br -Attempts to remove all device definitions i.e. reset the driver. This also runs -\fBmknodes\fP afterwards. Use with care! Open devices cannot be removed, but -adding \fB\-\-force\fP will replace the table with one that fails all I/O. -\fB\-\-deferred\fP will enable deferred removal of open devices - the device -will be removed when the last user closes it. The deferred removal feature is -supported since version 4.27.0 of the device-mapper driver available in -upstream kernel version 3.13. -. -.HP -.CMD_RENAME -.br -Renames a device. -. -.HP -.CMD_RENAME_UUID -.br -Sets the uuid of a device that was created without a uuid. -After a uuid has been set it cannot be changed. -. -.HP -.CMD_RESUME -.br -Un-suspends a device. -If an inactive table has been loaded, it becomes live. -Postponed I/O then gets re-queued for processing. -. -.HP -.CMD_SETGEOMETRY -.br -Sets the device geometry to C/H/S. -. -.HP -.CMD_SPLITNAME -.br -Splits given \fIdevice name\fP into \fIsubsystem\fP constituents. -The default subsystem is LVM. -LVM currently generates device names by concatenating the names of the Volume -Group, Logical Volume and any internal Layer with a hyphen as separator. -Any hyphens within the names are doubled to escape them. -The precise encoding might change without notice in any future -release, so we recommend you always decode using the current version of -this command. -.HP -.CMD_STATS -.br -Manages IO statistics regions for devices. -See -.BR dmstats (8) -for more details. -.HP -.CMD_STATUS -.br -Outputs status information for each of the device's targets. -With \fB\-\-target\fP, only information relating to the specified target type -any is displayed. With \fB\-\-noflush\fP, the thin target (from version 1.3.0) -doesn't commit any outstanding changes to disk before reporting its statistics. - -.HP -.CMD_SUSPEND -.br -Suspends a device. Any I/O that has already been mapped by the device -but has not yet completed will be flushed. Any further I/O to that -device will be postponed for as long as the device is suspended. -If there's a filesystem on the device which supports the operation, -an attempt will be made to sync it first unless \fB\-\-nolockfs\fP is specified. -Some targets such as recent (October 2006) versions of multipath may support -the \fB\-\-noflush\fP option. This lets outstanding I/O that has not yet reached the -device to remain unflushed. -. -.HP -.CMD_TABLE -.br -Outputs the current table for the device in a format that can be fed -back in using the create or load commands. -With \fB\-\-target\fP, only information relating to the specified target type -is displayed. -Real encryption keys are suppressed in the table output for the crypt -target unless the \fB\-\-showkeys\fP parameter is supplied. Kernel key -references prefixed with \fB:\fP are not affected by the parameter and get -displayed always. -. -.HP -.CMD_TARGETS -.br -Displays the names and versions of the currently-loaded targets. -. -.HP -.CMD_UDEVCOMPLETE -.br -Wake any processes that are waiting for udev to complete processing the specified cookie. -. -.HP -.CMD_UDEVCOMPLETE_ALL -.br -Remove all cookies older than the specified number of minutes. -Any process waiting on a cookie will be resumed immediately. -. -.HP -.CMD_UDEVCOOKIES -.br -List all existing cookies. Cookies are system-wide semaphores with keys -prefixed by two predefined bytes (0x0D4D). -. -.HP -.CMD_UDEVCREATECOOKIE -.br -Creates a new cookie to synchronize actions with udev processing. -The output is a cookie value. Normally we don't need to create cookies since -dmsetup creates and destroys them for each action automatically. However, we can -generate one explicitly to group several actions together and use only one -cookie instead. We can define a cookie to use for each relevant command by using -\fB\-\-udevcookie\fP option. Alternatively, we can export this value into the environment -of the dmsetup process as \fBDM_UDEV_COOKIE\fP variable and it will be used automatically -with all subsequent commands until it is unset. -Invoking this command will create system-wide semaphore that needs to be cleaned -up explicitly by calling udevreleasecookie command. -. -.HP -.CMD_UDEVFLAGS -.br -Parses given \fIcookie\fP value and extracts any udev control flags encoded. -The output is in environment key format that is suitable for use in udev -rules. If the flag has its symbolic name assigned then the output is -DM_UDEV_FLAG_ = '1', DM_UDEV_FLAG = '1' otherwise. -Subsystem udev flags don't have symbolic names assigned and these ones are -always reported as DM_SUBSYSTEM_UDEV_FLAG = '1'. There are -16 udev flags altogether. -. -.HP -.CMD_UDEVRELEASECOOKIE -.br -Waits for all pending udev processing bound to given cookie value and clean up -the cookie with underlying semaphore. If the cookie is not given directly, -the command will try to use a value defined by \fBDM_UDEV_COOKIE\fP environment variable. -. -.HP -.CMD_VERSION -.br -Outputs version information. -. -.HP -.CMD_WAIT -.br -Sleeps until the event counter for device_name exceeds event_nr. -Use \fB\-v\fP to see the event number returned. -To wait until the next event is triggered, use \fBinfo\fP to find -the last event number. -With \fB\-\-noflush\fP, the thin target (from version 1.3.0) doesn't commit -any outstanding changes to disk before reporting its statistics. -. -.HP -.CMD_WIPE_TABLE -.br -Wait for any I/O in-flight through the device to complete, then -replace the table with a new table that fails any new I/O -sent to the device. If successful, this should release any devices -held open by the device's table(s). -. -.SH TABLE FORMAT -. -Each line of the table specifies a single target and is of the form: -.sp -.I logical_start_sector num_sectors -.B target_type -.I target_args -.sp -Simple target types and target args include: -. -.TP -.B linear \fIdestination_device start_sector -The traditional linear mapping. -.TP -.B striped \fInum_stripes chunk_size \fR[\fIdestination start_sector\fR]... -Creates a striped area. -.br -e.g. striped 2 32 /dev/hda1 0 /dev/hdb1 0 -will map the first chunk (16k) as follows: -.RS -.RS - LV chunk 1 -> hda1, chunk 1 - LV chunk 2 -> hdb1, chunk 1 - LV chunk 3 -> hda1, chunk 2 - LV chunk 4 -> hdb1, chunk 2 - etc. -.RE -.RE -.TP -.B error -Errors any I/O that goes to this area. Useful for testing or -for creating devices with holes in them. -.TP -.B zero -Returns blocks of zeroes on reads. Any data written is discarded silently. -This is a block-device equivalent of the \fI/dev/zero\fP -character-device data sink described in \fBnull\fP(4). -.P -More complex targets include: -.TP -.B cache -Improves performance of a block device (eg, a spindle) by dynamically -migrating some of its data to a faster smaller device (eg, an SSD). -.TP -.B crypt -Transparent encryption of block devices using the kernel crypto API. -.TP -.B delay -Delays reads and/or writes to different devices. Useful for testing. -.TP -.B flakey -Creates a similar mapping to the linear target but -exhibits unreliable behaviour periodically. -Useful for simulating failing devices when testing. -.TP -.B mirror -Mirrors data across two or more devices. -.TP -.B multipath -Mediates access through multiple paths to the same device. -.TP -.B raid -Offers an interface to the kernel's software raid driver, md. -.TP -.B snapshot -Supports snapshots of devices. -.TP -.BR thin ", " thin-pool -Supports thin provisioning of devices and also provides a better snapshot support. -.P -To find out more about the various targets and their table formats and status -lines, please read the files in the Documentation/device-mapper directory in -the kernel source tree. -(Your distribution might include a copy of this information in the -documentation directory for the device-mapper package.) -. -.SH EXAMPLES -. -# A table to join two disks together -.br -0 1028160 linear /dev/hda 0 -.br -1028160 3903762 linear /dev/hdb 0 -.br -# A table to stripe across the two disks, -.br -# and add the spare space from -.br -# hdb to the back of the volume -.br -0 2056320 striped 2 32 /dev/hda 0 /dev/hdb 0 -.br -2056320 2875602 linear /dev/hdb 1028160 -. -.SH ENVIRONMENT VARIABLES -. -.TP -.B DM_DEV_DIR -The device directory name. -Defaults to "\fI/dev\fP" and must be an absolute path. -.TP -.B DM_UDEV_COOKIE -A cookie to use for all relevant commands to synchronize with udev processing. -It is an alternative to using \fB\-\-udevcookie\fP option. -.TP -.B DM_DEFAULT_NAME_MANGLING_MODE -A default mangling mode. Defaults to "\fB#DEFAULT_MANGLING#\fP" -and it is an alternative to using \fB\-\-manglename\fP option. -. -.SH AUTHORS -. -Original version: Joe Thornber -. -.SH SEE ALSO -. -.BR dmstats (8), -.BR udev (7), -.BR udevadm (8) -.P -LVM2 resource page: https://www.sourceware.org/lvm2/ -.br -Device-mapper resource page: http://sources.redhat.com/dm/ diff --git a/man/dmsetup.8_main b/man/dmsetup.8_main new file mode 100644 index 0000000..4261fc4 --- /dev/null +++ b/man/dmsetup.8_main @@ -0,0 +1,1026 @@ +.TH DMSETUP 8 "Apr 06 2006" "Linux" "MAINTENANCE COMMANDS" +. +.SH NAME +. +dmsetup \(em low level logical volume management +. +.SH SYNOPSIS +. +.\".nh +.ad l +.PD 0 +.HP 9 +.B dmsetup +.de CMD_CLEAR +. BR clear +. IR device_name +.. +.CMD_CLEAR +. +.HP +.B dmsetup +.de CMD_CREATE +. ad l +. BR create +. IR device_name +. RB [ -u | \-\-uuid +. IR uuid ] +. RB \%[ \-\-addnodeoncreate | \-\-addnodeonresume ] +. RB \%[ \-n | \-\-notable | \-\-table +. IR \%table | table_file ] +. RB [ \-\-readahead +. RB \%[ + ] \fIsectors | auto | none ] +. ad b +.. +.CMD_CREATE +. +.HP +.B dmsetup +.de CMD_DEPS +. ad l +. BR deps +. RB [ \-o +. IR options ] +. RI [ device_name ...] +. ad b +.. +.CMD_DEPS +. +.HP +.B dmsetup +.de CMD_HELP +. BR help +. RB [ \-c | \-C | \-\-columns ] +.. +.CMD_HELP +. +.HP +.B dmsetup +.de CMD_INFO +. BR info +. RI [ device_name ...] +.. +.CMD_INFO +. +.HP +.B dmsetup +.de CMD_INFOLONG +. ad l +. BR info +. BR \-c | \-C | \-\-columns +. RB [ \-\-count +. IR count ] +. RB [ \-\-interval +. IR seconds ] +. RB \%[ \-\-nameprefixes ] +. RB \%[ \-\-noheadings ] +. RB [ \-o +. IR fields ] +. RB [ \-O | \-\-sort +. IR sort_fields ] +. RB [ \-\-separator +. IR separator ] +. RI [ device_name ] +. ad b +.. +.CMD_INFOLONG +. +.HP +.B dmsetup +.de CMD_LOAD +. ad l +. BR load +. IR device_name +. RB [ \-\-table +. IR table | table_file ] +. ad b +.. +.CMD_LOAD +. +.HP +.B dmsetup +.de CMD_LS +. ad l +. BR ls +. RB [ \-\-target +. IR target_type ] +. RB [ \-\-exec +. IR command ] +. RB [ \-\-tree ] +. RB [ \-o +. IR options ] +. ad b +.. +.CMD_LS +. +.HP +.B dmsetup +.de CMD_MANGLE +. BR mangle +. RI [ device_name ...] +.. +.CMD_MANGLE +. +.HP +.B dmsetup +.de CMD_MESSAGE +. BR message +. IR device_name +. IR sector +. IR message +.. +.CMD_MESSAGE +. +.HP +.B dmsetup +.de CMD_MKNODES +. BR mknodes +. RI [ device_name ...] +.. +.CMD_MKNODES +. +.HP +.B dmsetup +.de CMD_RELOAD +. ad l +. BR reload +. IR device_name +. RB [ \-\-table +. IR table | table_file ] +. ad b +.. +.CMD_RELOAD +. +.HP +.B dmsetup +.de CMD_REMOVE +. ad l +. BR remove +. RB [ \-f | \-\-force ] +. RB [ \-\-retry ] +. RB [ \-\-deferred ] +. IR device_name ... +. ad b +.. +.CMD_REMOVE +. +.HP +.B dmsetup +.de CMD_REMOVE_ALL +. BR remove_all +. RB [ \-f | \-\-force ] +. RB [ \-\-deferred ] +.. +.CMD_REMOVE_ALL +. +.HP +.B dmsetup +.de CMD_RENAME +. BR rename +. IR device_name +. IR new_name +.. +.CMD_RENAME +. +.HP +.B dmsetup +.de CMD_RENAME_UUID +. BR rename +. IR device_name +. BR \-\-setuuid +. IR uuid +.. +.CMD_RENAME_UUID +. +.HP +.B dmsetup +.de CMD_RESUME +. ad l +. BR resume +. IR device_name ... +. RB [ \-\-addnodeoncreate | \-\-addnodeonresume ] +. RB [ \-\-noflush ] +. RB [ \-\-nolockfs ] +. RB \%[ \-\-readahead +. RB \%[ + ] \fIsectors | auto | none ] +. ad b +.. +.CMD_RESUME +. +.HP +.B dmsetup +.de CMD_SETGEOMETRY +. ad l +. BR setgeometry +. IR device_name +. IR cyl +. IR head +. IR sect +. IR start +. ad b +.. +.CMD_SETGEOMETRY +. +.HP +.B dmsetup +.de CMD_SPLITNAME +. BR splitname +. IR device_name +. RI [ subsystem ] +.. +.CMD_SPLITNAME +. +.HP +.B dmsetup +.de CMD_STATS +. BR stats +. IR command +. RI [ options ] +.. +.CMD_STATS +. +.HP +.B dmsetup +.de CMD_STATUS +. ad l +. BR status +. RB [ \-\-target +. IR target_type ] +. RB [ \-\-noflush ] +. RI [ device_name ...] +. ad b +.. +.CMD_STATUS +. +.HP +.B dmsetup +.de CMD_SUSPEND +. ad l +. BR suspend +. RB [ \-\-nolockfs ] +. RB [ \-\-noflush ] +. IR device_name ... +. ad b +.. +.CMD_SUSPEND +. +.HP +.B dmsetup +.de CMD_TABLE +. ad l +. BR table +. RB [ \-\-target +. IR target_type ] +. RB [ \-\-showkeys ] +. RI [ device_name ...] +. ad b +.. +.CMD_TABLE +. +.HP +.B dmsetup +.de CMD_TARGETS +. BR targets +.. +.CMD_TARGETS +. +.HP +.B dmsetup +.de CMD_UDEVCOMPLETE +. BR udevcomplete +. IR cookie +.. +.CMD_UDEVCOMPLETE +. +.HP +.B dmsetup +.de CMD_UDEVCOMPLETE_ALL +. BR udevcomplete_all +. RI [ age_in_minutes ] +.. +.CMD_UDEVCOMPLETE_ALL +. +.HP +.B dmsetup +.de CMD_UDEVCOOKIES +. BR udevcookie +.. +.CMD_UDEVCOOKIES +. +.HP +.B dmsetup +.de CMD_UDEVCREATECOOKIE +. BR udevcreatecookie +.. +.CMD_UDEVCREATECOOKIE +. +.HP +.B dmsetup +.de CMD_UDEVFLAGS +. BR udevflags +. IR cookie +.. +.CMD_UDEVFLAGS +. +.HP +.B dmsetup +.de CMD_UDEVRELEASECOOKIE +. BR udevreleasecookie +. RI [ cookie ] +.. +.CMD_UDEVRELEASECOOKIE +. +.HP +.B dmsetup +.de CMD_VERSION +. BR version +.. +.CMD_VERSION +. +.HP +.B dmsetup +.de CMD_WAIT +. ad l +. BR wait +. RB [ \-\-noflush ] +. IR device_name +. RI [ event_nr ] +. ad b +.. +.CMD_WAIT +. +.HP +.B dmsetup +.de CMD_WIPE_TABLE +. ad l +. BR wipe_table +. IR device_name ... +. RB [ \-f | \-\-force ] +. RB [ \-\-noflush ] +. RB [ \-\-nolockfs ] +. ad b +.. +.CMD_WIPE_TABLE +.PD +.P +.HP +.PD 0 +.B devmap_name \fImajor minor +.HP +.B devmap_name \fImajor:minor +.PD +.ad b +. +.SH DESCRIPTION +. +dmsetup manages logical devices that use the device-mapper driver. +Devices are created by loading a table that specifies a target for +each sector (512 bytes) in the logical device. + +The first argument to dmsetup is a command. +The second argument is the logical device name or uuid. + +Invoking the dmsetup tool as \fBdevmap_name\fP +(which is not normally distributed and is supported +only for historical reasons) is equivalent to +.BI \%dmsetup\ info\ \-c\ \-\-noheadings\ \-j \ major\ \-m \ minor \c +\fR. +.\" dot above here fixes -Thtml rendering for next HP option +. +.SH OPTIONS +. +.HP +.BR \-\-addnodeoncreate +.br +Ensure \fI/dev/mapper\fP node exists after \fBdmsetup create\fP. +. +.HP +.BR \-\-addnodeonresume +.br +Ensure \fI/dev/mapper\fP node exists after \fBdmsetup resume\fP (default with udev). +. +.HP +.BR \-\-checks +.br +Perform additional checks on the operations requested and report +potential problems. Useful when debugging scripts. +In some cases these checks may slow down operations noticeably. +. +.HP +.BR \-c | \-C | \-\-columns +.br +Display output in columns rather than as Field: Value lines. +. +.HP +.BR \-\-count +.IR count +.br +Specify the number of times to repeat a report. Set this to zero +continue until interrupted. The default interval is one second. +. +.HP +.BR \-f | \-\-force +.br +Try harder to complete operation. +. +.HP +.BR \-h | \-\-help +.br +Outputs a summary of the commands available, optionally including +the list of report fields (synonym with \fBhelp\fP command). +. +.HP +.BR \-\-inactive +.br +When returning any table information from the kernel report on the +inactive table instead of the live table. +Requires kernel driver version 4.16.0 or above. +. +.HP +.BR \-\-interval +.IR seconds +.br +Specify the interval in seconds between successive iterations for +repeating reports. If \fB\-\-interval\fP is specified but \fB\-\-count\fP +is not, reports will continue to repeat until interrupted. +The default interval is one second. +. +.HP +.BR \-\-manglename +.BR auto | hex | none +.br +Mangle any character not on a whitelist using mangling_mode when +processing device-mapper device names and UUIDs. The names and UUIDs +are mangled on input and unmangled on output where the mangling mode +is one of: +\fBauto\fP (only do the mangling if not mangled yet, do nothing +if already mangled, error on mixed), +\fBhex\fP (always do the mangling) and +\fBnone\fP (no mangling). +Default mode is \fB#DEFAULT_MANGLING#\fP. +Character whitelist: 0-9, A-Z, a-z, #+-.:=@_. This whitelist is +also supported by udev. Any character not on a whitelist is replaced +with its hex value (two digits) prefixed by \\x. +Mangling mode could be also set through +\fBDM_DEFAULT_NAME_MANGLING_MODE\fP +environment variable. +. +.HP +.BR \-j | \-\-major +.IR major +.br +Specify the major number. +. +.HP +.BR \-m | \-\-minor +.IR minor +.br +Specify the minor number. +. +.HP +.BR \-n | \-\-notable +.br +When creating a device, don't load any table. +. +.HP +.BR \-\-nameprefixes +.br +Add a "DM_" prefix plus the field name to the output. Useful with +\fB\-\-noheadings\fP to produce a list of +field=value pairs that can be used to set environment variables +(for example, in +.BR udev (7) +rules). +. +.HP +.BR \-\-noheadings +Suppress the headings line when using columnar output. +. +.HP +.BR \-\-noflush +Do not flush outstading I/O when suspending a device, or do not +commit thin-pool metadata when obtaining thin-pool status. +. +.HP +.BR \-\-nolockfs +.br +Do not attempt to synchronize filesystem eg, when suspending a device. +. +.HP +.BR \-\-noopencount +.br +Tell the kernel not to supply the open reference count for the device. +. +.HP +.BR \-\-noudevrules +.br +Do not allow udev to manage nodes for devices in device-mapper directory. +. +.HP +.BR \-\-noudevsync +.br +Do not synchronise with udev when creating, renaming or removing devices. +. +.HP +.BR \-o | \-\-options +.IR options +.br +Specify which fields to display. +. +.HP +.BR \-\-readahead +.RB [ + ] \fIsectors | auto | none +.br +Specify read ahead size in units of sectors. +The default value is \fBauto\fP which allows the kernel to choose +a suitable value automatically. The \fB+\fP prefix lets you +specify a minimum value which will not be used if it is +smaller than the value chosen by the kernel. +The value \fBnone\fP is equivalent to specifying zero. +. +.HP +.BR \-r | \-\-readonly +.br +Set the table being loaded read-only. +. +.HP +.BR \-S | \-\-select +.IR selection +.br +Display only rows that match \fIselection\fP criteria. All rows are displayed +with the additional "selected" column (\fB-o selected\fP) showing 1 if the row +matches the \fIselection\fP and 0 otherwise. The selection criteria are defined +by specifying column names and their valid values while making use of +supported comparison operators. As a quick help and to see full list of +column names that can be used in selection and the set of supported +selection operators, check the output of \fBdmsetup\ info\ -c\ -S\ help\fP +command. +. +.HP +.BR \-\-table +.IR table +.br +Specify a one-line table directly on the command line. +See below for more information on the table format. +. +.HP +.BR \-\-udevcookie +.IR cookie +.br +Use cookie for udev synchronisation. +Note: Same cookie should be used for same type of operations i.e. creation of +multiple different devices. It's not adviced to combine different +operations on the single device. +. +.HP +.BR \-u | \-\-uuid +.br +Specify the \fIuuid\fP. +. +.HP +.BR \-y | \-\-yes +.br +Answer yes to all prompts automatically. +. +.HP +.BR \-v | \-\-verbose +.RB [ \-v | \-\-verbose ] +.br +Produce additional output. +. +.HP +.BR \-\-verifyudev +.br +If udev synchronisation is enabled, verify that udev operations get performed +correctly and try to fix up the device nodes afterwards if not. +. +.HP +.BR \-\-version +.br +Display the library and kernel driver version. +.br +. +.SH COMMANDS +. +.HP +.CMD_CLEAR +.br +Destroys the table in the inactive table slot for device_name. +. +.HP +.CMD_CREATE +.br +Creates a device with the given name. +If \fItable\fP or \fItable_file\fP is supplied, the table is loaded and made live. +Otherwise a table is read from standard input unless \fB\-\-notable\fP is used. +The optional \fIuuid\fP can be used in place of +device_name in subsequent dmsetup commands. +If successful the device will appear in table and for live +device the node \fI/dev/mapper/device_name\fP is created. +See below for more information on the table format. +. +.HP +.CMD_DEPS +.br +Outputs a list of devices referenced by the live table for the specified +device. Device names on output can be customised by following \fIoptions\fP: +\fBdevno\fP (major and minor pair, used by default), +\fBblkdevname\fP (block device name), +\fBdevname\fP (map name for device-mapper devices, equal to blkdevname otherwise). +. +.HP +.CMD_HELP +.br +Outputs a summary of the commands available, optionally including +the list of report fields. +. +.HP +.CMD_INFO +.br +Outputs some brief information about the device in the form: +.RS +.RS + State: SUSPENDED|ACTIVE, READ-ONLY + Tables present: LIVE and/or INACTIVE + Open reference count + Last event sequence number (used by \fBwait\fP) + Major and minor device number + Number of targets in the live table + UUID +.RE +.RE +.HP +.CMD_INFOLONG +.br +Output you can customise. +Fields are comma-separated and chosen from the following list: +.BR name , +.BR major , +.BR minor , +.BR attr , +.BR open , +.BR segments , +.BR events , +.BR uuid . +Attributes are: +.RI ( L )ive, +.RI ( I )nactive, +.RI ( s )uspended, +.RI ( r )ead-only, +.RI read-( w )rite. +Precede the list with '\fB+\fP' to append +to the default selection of columns instead of replacing it. +Precede any sort field with '\fB-\fP' for a reverse sort on that column. +. +.HP +.CMD_LS +.br +List device names. Optionally only list devices that have at least +one target of the specified type. Optionally execute a command for +each device. The device name is appended to the supplied command. +Device names on output can be customised by following options: +\fBdevno\fP (major and minor pair, used by default), +\fBblkdevname\fP (block device name), +\fBdevname\fP (map name for device-mapper devices, equal to blkdevname otherwise). +\fB\-\-tree\fP displays dependencies between devices as a tree. +It accepts a comma-separate list of \fIoptions\fP. +Some specify the information displayed against each node: +.BR device / nodevice ; +.BR blkdevname ; +.BR active ", " open ", " rw ", " uuid . +Others specify how the tree is displayed: +.BR ascii ", " utf ", " vt100 ; +.BR compact ", " inverted ", " notrunc . +. +.HP +.BR load | \c +.CMD_RELOAD +.br +Loads \fItable\fP or \fItable_file\fP into the inactive table slot for device_name. +If neither is supplied, reads a table from standard input. +. +.HP +.CMD_MANGLE +.br +Ensure existing device-mapper \fIdevice_name\fP and UUID is in the correct mangled +form containing only whitelisted characters (supported by udev) and do +a rename if necessary. Any character not on the whitelist will be mangled +based on the \fB\-\-manglename\fP setting. Automatic rename works only for device +names and not for device UUIDs because the kernel does not allow changing +the UUID of active devices. Any incorrect UUIDs are reported only and they +must be manually corrected by deactivating the device first and then +reactivating it with proper mangling mode used (see also \fB\-\-manglename\fP). +. +.HP +.CMD_MESSAGE +.br +Send message to target. If sector not needed use 0. +. +.HP +.CMD_MKNODES +.br +Ensure that the node in \fI/dev/mapper\fP for \fIdevice_name\fP is correct. +If no device_name is supplied, ensure that all nodes in \fI/dev/mapper\fP +correspond to mapped devices currently loaded by the device-mapper kernel +driver, adding, changing or removing nodes as necessary. +. +.HP +.CMD_REMOVE +.br +Removes a device. It will no longer be visible to dmsetup. Open devices +cannot be removed, but adding \fB\-\-force\fP will replace the table with one +that fails all I/O. \fB\-\-deferred\fP will enable deferred removal of open +devices - the device will be removed when the last user closes it. The deferred +removal feature is supported since version 4.27.0 of the device-mapper +driver available in upstream kernel version 3.13. (Use \fBdmsetup version\fP +to check this.) If an attempt to remove a device fails, perhaps because a process run +from a quick udev rule temporarily opened the device, the \fB\-\-retry\fP +option will cause the operation to be retried for a few seconds before failing. +Do NOT combine +\fB\-\-force\fP and \fB\-\-udevcookie\fP, as udev may start to process udev +rules in the middle of error target replacement and result in nondeterministic +result. +. +.HP +.CMD_REMOVE_ALL +.br +Attempts to remove all device definitions i.e. reset the driver. This also runs +\fBmknodes\fP afterwards. Use with care! Open devices cannot be removed, but +adding \fB\-\-force\fP will replace the table with one that fails all I/O. +\fB\-\-deferred\fP will enable deferred removal of open devices - the device +will be removed when the last user closes it. The deferred removal feature is +supported since version 4.27.0 of the device-mapper driver available in +upstream kernel version 3.13. +. +.HP +.CMD_RENAME +.br +Renames a device. +. +.HP +.CMD_RENAME_UUID +.br +Sets the uuid of a device that was created without a uuid. +After a uuid has been set it cannot be changed. +. +.HP +.CMD_RESUME +.br +Un-suspends a device. +If an inactive table has been loaded, it becomes live. +Postponed I/O then gets re-queued for processing. +. +.HP +.CMD_SETGEOMETRY +.br +Sets the device geometry to C/H/S. +. +.HP +.CMD_SPLITNAME +.br +Splits given \fIdevice name\fP into \fIsubsystem\fP constituents. +The default subsystem is LVM. +LVM currently generates device names by concatenating the names of the Volume +Group, Logical Volume and any internal Layer with a hyphen as separator. +Any hyphens within the names are doubled to escape them. +The precise encoding might change without notice in any future +release, so we recommend you always decode using the current version of +this command. +.HP +.CMD_STATS +.br +Manages IO statistics regions for devices. +See +.BR dmstats (8) +for more details. +.HP +.CMD_STATUS +.br +Outputs status information for each of the device's targets. +With \fB\-\-target\fP, only information relating to the specified target type +any is displayed. With \fB\-\-noflush\fP, the thin target (from version 1.3.0) +doesn't commit any outstanding changes to disk before reporting its statistics. + +.HP +.CMD_SUSPEND +.br +Suspends a device. Any I/O that has already been mapped by the device +but has not yet completed will be flushed. Any further I/O to that +device will be postponed for as long as the device is suspended. +If there's a filesystem on the device which supports the operation, +an attempt will be made to sync it first unless \fB\-\-nolockfs\fP is specified. +Some targets such as recent (October 2006) versions of multipath may support +the \fB\-\-noflush\fP option. This lets outstanding I/O that has not yet reached the +device to remain unflushed. +. +.HP +.CMD_TABLE +.br +Outputs the current table for the device in a format that can be fed +back in using the create or load commands. +With \fB\-\-target\fP, only information relating to the specified target type +is displayed. +Real encryption keys are suppressed in the table output for the crypt +target unless the \fB\-\-showkeys\fP parameter is supplied. Kernel key +references prefixed with \fB:\fP are not affected by the parameter and get +displayed always. +. +.HP +.CMD_TARGETS +.br +Displays the names and versions of the currently-loaded targets. +. +.HP +.CMD_UDEVCOMPLETE +.br +Wake any processes that are waiting for udev to complete processing the specified cookie. +. +.HP +.CMD_UDEVCOMPLETE_ALL +.br +Remove all cookies older than the specified number of minutes. +Any process waiting on a cookie will be resumed immediately. +. +.HP +.CMD_UDEVCOOKIES +.br +List all existing cookies. Cookies are system-wide semaphores with keys +prefixed by two predefined bytes (0x0D4D). +. +.HP +.CMD_UDEVCREATECOOKIE +.br +Creates a new cookie to synchronize actions with udev processing. +The output is a cookie value. Normally we don't need to create cookies since +dmsetup creates and destroys them for each action automatically. However, we can +generate one explicitly to group several actions together and use only one +cookie instead. We can define a cookie to use for each relevant command by using +\fB\-\-udevcookie\fP option. Alternatively, we can export this value into the environment +of the dmsetup process as \fBDM_UDEV_COOKIE\fP variable and it will be used automatically +with all subsequent commands until it is unset. +Invoking this command will create system-wide semaphore that needs to be cleaned +up explicitly by calling udevreleasecookie command. +. +.HP +.CMD_UDEVFLAGS +.br +Parses given \fIcookie\fP value and extracts any udev control flags encoded. +The output is in environment key format that is suitable for use in udev +rules. If the flag has its symbolic name assigned then the output is +DM_UDEV_FLAG_ = '1', DM_UDEV_FLAG = '1' otherwise. +Subsystem udev flags don't have symbolic names assigned and these ones are +always reported as DM_SUBSYSTEM_UDEV_FLAG = '1'. There are +16 udev flags altogether. +. +.HP +.CMD_UDEVRELEASECOOKIE +.br +Waits for all pending udev processing bound to given cookie value and clean up +the cookie with underlying semaphore. If the cookie is not given directly, +the command will try to use a value defined by \fBDM_UDEV_COOKIE\fP environment variable. +. +.HP +.CMD_VERSION +.br +Outputs version information. +. +.HP +.CMD_WAIT +.br +Sleeps until the event counter for device_name exceeds event_nr. +Use \fB\-v\fP to see the event number returned. +To wait until the next event is triggered, use \fBinfo\fP to find +the last event number. +With \fB\-\-noflush\fP, the thin target (from version 1.3.0) doesn't commit +any outstanding changes to disk before reporting its statistics. +. +.HP +.CMD_WIPE_TABLE +.br +Wait for any I/O in-flight through the device to complete, then +replace the table with a new table that fails any new I/O +sent to the device. If successful, this should release any devices +held open by the device's table(s). +. +.SH TABLE FORMAT +. +Each line of the table specifies a single target and is of the form: +.sp +.I logical_start_sector num_sectors +.B target_type +.I target_args +.sp +Simple target types and target args include: +. +.TP +.B linear \fIdestination_device start_sector +The traditional linear mapping. +.TP +.B striped \fInum_stripes chunk_size \fR[\fIdestination start_sector\fR]... +Creates a striped area. +.br +e.g. striped 2 32 /dev/hda1 0 /dev/hdb1 0 +will map the first chunk (16k) as follows: +.RS +.RS + LV chunk 1 -> hda1, chunk 1 + LV chunk 2 -> hdb1, chunk 1 + LV chunk 3 -> hda1, chunk 2 + LV chunk 4 -> hdb1, chunk 2 + etc. +.RE +.RE +.TP +.B error +Errors any I/O that goes to this area. Useful for testing or +for creating devices with holes in them. +.TP +.B zero +Returns blocks of zeroes on reads. Any data written is discarded silently. +This is a block-device equivalent of the \fI/dev/zero\fP +character-device data sink described in \fBnull\fP(4). +.P +More complex targets include: +.TP +.B cache +Improves performance of a block device (eg, a spindle) by dynamically +migrating some of its data to a faster smaller device (eg, an SSD). +.TP +.B crypt +Transparent encryption of block devices using the kernel crypto API. +.TP +.B delay +Delays reads and/or writes to different devices. Useful for testing. +.TP +.B flakey +Creates a similar mapping to the linear target but +exhibits unreliable behaviour periodically. +Useful for simulating failing devices when testing. +.TP +.B mirror +Mirrors data across two or more devices. +.TP +.B multipath +Mediates access through multiple paths to the same device. +.TP +.B raid +Offers an interface to the kernel's software raid driver, md. +.TP +.B snapshot +Supports snapshots of devices. +.TP +.BR thin ", " thin-pool +Supports thin provisioning of devices and also provides a better snapshot support. +.P +To find out more about the various targets and their table formats and status +lines, please read the files in the Documentation/device-mapper directory in +the kernel source tree. +(Your distribution might include a copy of this information in the +documentation directory for the device-mapper package.) +. +.SH EXAMPLES +. +# A table to join two disks together +.br +0 1028160 linear /dev/hda 0 +.br +1028160 3903762 linear /dev/hdb 0 +.br +# A table to stripe across the two disks, +.br +# and add the spare space from +.br +# hdb to the back of the volume +.br +0 2056320 striped 2 32 /dev/hda 0 /dev/hdb 0 +.br +2056320 2875602 linear /dev/hdb 1028160 +. +.SH ENVIRONMENT VARIABLES +. +.TP +.B DM_DEV_DIR +The device directory name. +Defaults to "\fI/dev\fP" and must be an absolute path. +.TP +.B DM_UDEV_COOKIE +A cookie to use for all relevant commands to synchronize with udev processing. +It is an alternative to using \fB\-\-udevcookie\fP option. +.TP +.B DM_DEFAULT_NAME_MANGLING_MODE +A default mangling mode. Defaults to "\fB#DEFAULT_MANGLING#\fP" +and it is an alternative to using \fB\-\-manglename\fP option. +. +.SH AUTHORS +. +Original version: Joe Thornber +. +.SH SEE ALSO +. +.BR dmstats (8), +.BR udev (7), +.BR udevadm (8) +.P +LVM2 resource page: https://www.sourceware.org/lvm2/ +.br +Device-mapper resource page: http://sources.redhat.com/dm/ diff --git a/man/dmstats.8.in b/man/dmstats.8.in deleted file mode 100644 index 682f01d..0000000 --- a/man/dmstats.8.in +++ /dev/null @@ -1,1284 +0,0 @@ -.TH DMSTATS 8 "Jun 23 2016" "Linux" "MAINTENANCE COMMANDS" - -.de OPT_PROGRAMS -. RB \%[ \-\-allprograms | \-\-programid -. IR id ] -.. -. -.de OPT_REGIONS -. RB \%[ \-\-allregions | \-\-regionid -. IR id ] -.. -.de OPT_OBJECTS -. RB [ \-\-area ] -. RB [ \-\-region ] -. RB [ \-\-group ] -.. -.de OPT_FOREGROUND -. RB [ \-\-foreground ] -.. -. -.\" Print units suffix, use with arg to print human -.\" man2html can't handle too many changes per command -.de UNITS -. BR b | B | s | S | k | K | m | M | \c -. BR g | G | t | T | p | P | e | E ] -.. -. -.\" Print help text for units, use with arg to print human -.de HELP_UNITS -. RB ( b )ytes, -. RB ( s )ectors, -. RB ( k )ilobytes, -. RB ( m )egabytes, -. RB ( g )igabytes, -. RB ( t )erabytes, -. RB ( p )etabytes, -. RB ( e )xabytes. -. nop Capitalise to use multiples of 1000 (S.I.) instead of 1024. -.. -. -.SH NAME -. -dmstats \(em device-mapper statistics management -. -.SH SYNOPSIS -. -.B dmsetup -.B stats -.I command -[OPTIONS] -.sp -. -.PD 0 -.HP -.B dmstats -.de CMD_COMMAND -. ad l -. IR command -. IR device_name " |" -. BR \-\-major -. IR major -. BR \-\-minor -. IR minor " |" -. BR \-u | \-\-uuid -. IR uuid -. RB \%[ \-v | \-\-verbose] -. ad b -.. -.CMD_COMMAND -. -.HP -.B dmstats -.de CMD_CLEAR -. ad l -. BR clear -. IR device_name -. OPT_PROGRAMS -. OPT_REGIONS -. ad b -.. -.CMD_CLEAR -. -.HP -.B dmstats -.de CMD_CREATE -. ad l -. BR create -. IR device_name... | file_path... | \fB\-\-alldevices -. RB [ \-\-areas -. IR nr_areas | \fB\-\-areasize -. IR area_size ] -. RB [ \-\-bounds -. IR \%histogram_boundaries ] -. RB [ \-\-filemap ] -. RB [ \-\-follow -. IR follow_mode ] -. OPT_FOREGROUND -. RB [ \-\-nomonitor ] -. RB [ \-\-nogroup ] -. RB [ \-\-precise ] -. RB [ \-\-start -. IR start_sector -. BR \-\-length -. IR length | \fB\-\-segments ] -. RB \%[ \-\-userdata -. IR user_data ] -. RB [ \-\-programid -. IR id ] -. ad b -.. -.CMD_CREATE -. -.HP -.B dmstats -.de CMD_DELETE -. ad l -. BR delete -. IR device_name | \fB\-\-alldevices -. OPT_PROGRAMS -. OPT_REGIONS -. ad b -.. -.CMD_DELETE -. -.HP -.B dmstats -.de CMD_GROUP -. ad l -. BR group -. RI [ device_name | \fB\-\-alldevices ] -. RB [ \-\-alias -. IR name ] -. RB [ \-\-regions -. IR regions ] -. ad b -.. -.CMD_GROUP -.HP -.B dmstats -.de CMD_HELP -. ad l -. BR help -. RB [ \-c | \-C | \-\-columns ] -. ad b -.. -.CMD_HELP -. -.HP -.B dmstats -.de CMD_LIST -. ad l -. BR list -. RI [ device_name ] -. RB [ \-\-histogram ] -. OPT_PROGRAMS -. RB [ \-\-units -. IR units ] -. OPT_OBJECTS -. RB \%[ \-\-nosuffix ] -. RB [ \-\-notimesuffix ] -. RB \%[ \-v | \-\-verbose] -. ad b -.. -.CMD_LIST -. -.HP -.B dmstats -.de CMD_PRINT -. ad l -. BR print -. RI [ device_name ] -. RB [ \-\-clear ] -. OPT_PROGRAMS -. OPT_REGIONS -. ad b -.. -.CMD_PRINT -. -.HP -.B dmstats -.de CMD_REPORT -. ad l -. BR report -. RI [ device_name ] -. RB [ \-\-interval -. IR seconds ] -. RB [ \-\-count -. IR count ] -. RB [ \-\-units -. IR units ] -. RB [ \-\-histogram ] -. OPT_PROGRAMS -. OPT_REGIONS -. OPT_OBJECTS -. RB [ \-O | \-\-sort -. IR sort_fields ] -. RB [ \-S | \-\-select -. IR selection ] -. RB [ \-\-units -. IR units ] -. RB [ \-\-nosuffix ] -. RB \%[ \-\-notimesuffix ] -. ad b -.. -.CMD_REPORT -.HP -.B dmstats -.de CMD_UNGROUP -. ad l -. BR ungroup -. RI [ device_name | \fB\-\-alldevices ] -. RB [ \-\-groupid -. IR id ] -. ad b -.. -.CMD_UNGROUP -.HP -.B dmstats -.de CMD_UPDATE_FILEMAP -. ad l -. BR update_filemap -. IR file_path -. RB [ \-\-groupid -. IR id ] -. RB [ \-\-follow -. IR follow_mode ] -. OPT_FOREGROUND -. ad b -.. -.CMD_UPDATE_FILEMAP -. -.PD -.ad b -. -.SH DESCRIPTION -. -The dmstats program manages IO statistics regions for devices that use -the device-mapper driver. Statistics regions may be created, deleted, -listed and reported on using the tool. - -The first argument to dmstats is a \fIcommand\fP. - -The second argument is the \fIdevice name\fP, -\fIuuid\fP or \fImajor\fP and \fIminor\fP numbers. - -Further options permit the selection of regions, output format -control, and reporting behaviour. - -When no device argument is given dmstats will by default operate on all -device-mapper devices present. The \fBcreate\fP and \fBdelete\fP -commands require the use of \fB\-\-alldevices\fP when used in this way. -. -.SH OPTIONS -. -.HP -.BR \-\-alias -.IR name -.br -Specify an alias name for a group. -. -.HP -.BR \-\-alldevices -.br -If no device arguments are given allow operation on all devices when -creating or deleting regions. -. -.HP -.BR \-\-allprograms -.br -Include regions from all program IDs for list and report operations. -.br -.HP -.BR \-\-allregions -.br -Include all present regions for commands that normally accept a single -region identifier. -. -.HP -.BR \-\-area -.br -When peforming a list or report, include objects of type area in the -results. -. -.HP -.BR \-\-areas -.IR nr_areas -.br -Specify the number of statistics areas to create within a new region. -. -.HP -.BR \-\-areasize -.IR area_size \c -.RB [ \c -.UNITS -.br -Specify the size of areas into which a new region should be divided. An -optional suffix selects units of: -.HELP_UNITS -. -.HP -.BR \-\-clear -.br -When printing statistics counters, also atomically reset them to zero. -. -.HP -.BR \-\-count -.IR count -.br -Specify the iteration count for repeating reports. If the count -argument is zero reports will continue to repeat until interrupted. -. -.HP -.BR \-\-group -.br -When peforming a list or report, include objects of type group in the -results. -. -.HP -.BR \-\-filemap -.br -Instead of creating regions on a device as specified by command line -options, open the file found at each \fBfile_path\fP argument, and -create regions corresponding to the locations of the on-disk extents -allocated to the file(s). -. -.HP -.BR \-\-nomonitor -.br -Disable the \fBdmfilemapd\fP daemon when creating new file mapped -groups. Normally the device-mapper filemap monitoring daemon, -\fBdmfilemapd\fP, is started for each file mapped group to update the -set of regions as the file changes on-disk: use of this option -disables this behaviour. - -Regions in the group may still be updated with the -\fBupdate_filemap\fP command, or by starting the daemon manually. -. -.HP -.BR \-\-follow -.IR follow_mode -.br -Specify the \fBdmfilemapd\fP file following mode. 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. - -The \fBfollow_mode\fP argument is either "inode", for follow-inode -mode, or "path", for follow-path. - -If follow-inode mode is used, the daemon will hold the file open, and -continue to update regions from the same file descriptor. This means -that the mapping will follow rename, move (within the same file -system), and unlink operations. This mode is useful if the file is -expected to be moved, renamed, or unlinked while it is being -monitored. - -In follow-inode mode, the daemon will exit once it detects that the -file has been unlinked and it is the last holder of a reference to it. - -If follow-path is used, the daemon will re-open the provided path on -each monitoring iteration. This means that the group will be updated -to reflect a new file being moved to the same path as the original -file. This mode is useful for files that are expected to be updated -via unlink and rename. - -In follow-path mode, the daemon will exit if the file is removed and -not replaced within a brief tolerance interval. - -In either mode, the daemon exits automatically if the monitored group -is removed. -. -.HP -.BR \-\-foreground -.br -Specify that the \fBdmfilemapd\fP daemon should run in the foreground. -The daemon will not fork into the background, and will replace the -\fBdmstats\fP command that started it. -. -.HP -.BR \-\-groupid -.IR id -.br -Specify the group to operate on. -. -.HP -.BR \-\-bounds -.IR histogram_boundaries \c -.RB [ ns | us | ms | s ] -.br -Specify the boundaries of a latency histogram to be tracked for the -region as a comma separated list of latency values. Latency values are -given in nanoseconds. An optional unit suffix of -.BR ns , -.BR us , -.BR ms , -or \fBs\fP may be given after each value to specify units of -nanoseconds, microseconds, miliseconds or seconds respectively. -. -.HP -.BR \-\-histogram -.br -When used with the \fBreport\fP and \fBlist\fP commands select default -fields that emphasize latency histogram data. -. -.HP -.BR \-\-interval -.IR seconds -.br -Specify the interval in seconds between successive iterations for -repeating reports. If \fB\-\-interval\fP is specified but -\fB\-\-count\fP is not, -reports will continue to repeat until interrupted. -. -.HP -.BR \-\-length -.IR length \c -.RB [ \c -.UNITS -.br -Specify the length of a new statistics region in sectors. An optional -suffix selects units of: -.HELP_UNITS -. -.HP -.BR \-j | \-\-major -.IR major -.br -Specify the major number. -. -.HP -.BR \-m | \-\-minor -.IR minor -.br -Specify the minor number. -. -.HP -.BR \-\-nogroup -.br -When creating regions mapping the extents of a file in the file -system, do not create a group or set an alias. -. -.HP -.BR \-\-nosuffix -.br -Suppress the suffix on output sizes. Use with \fB\-\-units\fP -(except h and H) if processing the output. -. -.HP -.BR \-\-notimesuffix -.br -Suppress the suffix on output time values. Histogram boundary values -will be reported in units of nanoseconds. -. -.HP -.BR \-o | \-\-options -.br -Specify which report fields to display. -. -.HP -.BR \-O | \-\-sort -.IR sort_fields -.br -Sort output according to the list of fields given. Precede any -sort field with '\fB-\fP' for a reverse sort on that column. -. -.HP -.BR \-\-precise -.br -Attempt to use nanosecond precision counters when creating new -statistics regions. -. -.HP -.BR \-\-programid -.IR id -.br -Specify a program ID string. When creating new statistics regions this -string is stored with the region. Subsequent operations may supply a -program ID in order to select only regions with a matching value. The -default program ID for dmstats-managed regions is "dmstats". -. -.HP -.BR \-\-region -.br -When peforming a list or report, include objects of type region in the -results. -. -.HP -.BR \-\-regionid -.IR id -.br -Specify the region to operate on. -. -.HP -.BR \-\-regions -.IR region_list -.br -Specify a list of regions to group. The group list is a comma-separated -list of region identifiers. Continuous sequences of identifiers may be -expressed as a hyphen separated range, for example: '1-10'. -. -.HP -.BR \-\-relative -.br -If displaying the histogram report show relative (percentage) values -instead of absolute counts. -. -.HP -.BR \-S | \-\-select -.IR selection -.br -Display only rows that match \fIselection\fP criteria. All rows with the -additional "selected" column (\fB\-o selected\fP) showing 1 if the row matches -the \fIselection\fP and 0 otherwise. The selection criteria are defined by -specifying column names and their valid values while making use of -supported comparison operators. -. -.HP -.BR \-\-start -.IR start \c -.RB [ \c -.UNITS -.br -Specify the start offset of a new statistics region in sectors. An -optional suffix selects units of: -.HELP_UNITS -. -.HP -.BR \-\-segments -.br -When used with \fBcreate\fP, create a new statistics region for each -target contained in the given device(s). This causes a separate region -to be allocated for each segment of the device. - -The newly created regions are automatically placed into a group unless -the \fB\-\-nogroup\fP option is given. When grouping is enabled a group -alias may be specified using the \fB\-\-alias\fP option. -. -.HP -.BR \-\-units -.RI [ units ] \c -.RB [ h | H | \c -.UNITS -.br -Set the display units for report output. -All sizes are output in these units: -.RB ( h )uman-readable, -.HELP_UNITS -Can also specify custom units e.g. \fB\-\-units\ 3M\fP. -. -.HP -.BR \-\-userdata -.IR user_data -.br -Specify user data (a word) to be stored with a new region. The value -is added to any internal auxilliary data (for example, group -information), and stored with the region in the aux_data field provided -by the kernel. Whitespace is not permitted. -. -.HP -.BR \-u | \-\-uuid -.br -Specify the uuid. -. -.HP -.BR \-v | \-\-verbose " [" \-v | \-\-verbose ] -.br -Produce additional output. -. -.SH COMMANDS -. -.HP -.CMD_CLEAR -.br -Instructs the kernel to clear statistics counters for the speficied -regions (with the exception of in-flight IO counters). -. -.HP -.CMD_CREATE -.br -Creates one or more new statistics regions on the specified device(s). - -The region will span the entire device unless \fB\-\-start\fP and -\fB\-\-length\fP or \fB\-\-segments\fP are given. The \fB\-\-start\fP an -\fB\-\-length\fP options allow a region of arbitrary length to be placed -at an arbitrary offset into the device. The \fB\-\-segments\fP option -causes a new region to be created for each target in the corresponding -device-mapper device's table. - -If the \fB\-\-precise\fP option is used the command will attempt to -create a region using nanosecond precision counters. - -If \fB\-\-bounds\fP is given a latency histogram will be tracked for -the new region. The boundaries of the histogram bins are given as a -comma separated list of latency values. There is an implicit lower bound -of zero on the first bin and an implicit upper bound of infinity (or the -configured interval duration) on the final bin. - -Latencies are given in nanoseconds. An optional unit suffix of ns, us, -ms, or s may be given after each value to specify units of nanoseconds, -microseconds, miliseconds or seconds respectively, so for example, 10ms -is equivalent to 10000000. Latency values with a precision of less than -one milisecond can only be used when precise timestamps are enabled: if -\fB\-\-precise\fP is not given and values less than one milisecond are -used it will be enabled automatically. - -An optional \fBprogram_id\fP or \fBuser_data\fP string may be associated -with the region. A \fBprogram_id\fP may then be used to select regions -for subsequent list, print, and report operations. The \fBuser_data\fP -stores an arbitrary string and is not used by dmstats or the -device-mapper kernel statistics subsystem. - -By default dmstats creates regions with a \fBprogram_id\fP of -"dmstats". - -On success the \fBregion_id\fP of the newly created region is printed -to stdout. - -If the \fB\-\-filemap\fP option is given with a regular file, or list -of files, as the \fBfile_path\fP argument, instead of creating regions -with parameters specified on the command line, \fBdmstats\fP will open -the files located at \fBfile_path\fP and create regions corresponding to -the physical extents allocated to the file. This can be used to monitor -statistics for individual files in the file system, for example, virtual -machine images, swap areas, or large database files. - -To work with the \fB\-\-filemap\fP option, files must be located on a -local file system, backed by a device-mapper device, that supports -physical extent data using the FIEMAP ioctl (Ext4 and XFS for e.g.). - -By default regions that map a file are placed into a group and the -group alias is set to the basename of the file. This behaviour can be -overridden with the \fB\-\-alias\fP and \fB\-\-nogroup\fP options. - -Creating a group that maps a file automatically starts a daemon, -\fBdmfilemapd\fP to monitor the file and update the mapping as the -extents allocated to the file change. This behaviour can be disabled -using the \fB\-\-nomonitor\fP option. - -Use the \fB\-\-group\fP option to only display information for groups -when listing and reporting. -. -.HP -.CMD_DELETE -.br -Delete the specified statistics region. All counters and resources used -by the region are released and the region will not appear in the output -of subsequent list, print, or report operations. - -All regions registered on a device may be removed using -\fB\-\-allregions\fP. - -To remove all regions on all devices both \fB\-\-allregions\fP and -\fB\-\-alldevices\fP must be used. - -If a \fB\-\-groupid\fP is given instead of a \fB\-\-regionid\fP the -command will attempt to delete the group and all regions that it -contains. - -If a deleted region is the first member of a group of regions the group -will also be removed. -. -.HP -.CMD_GROUP -.br -Combine one or more statistics regions on the specified device into a -group. - -The list of regions to be grouped is specified with \fB\-\-regions\fP -and an optional alias may be assigned with \fB\-\-alias\fP. The set of -regions is given as a comma-separated list of region identifiers. A -continuous range of identifers spanning from \fBR1\fP to \fBR2\fP may -be expressed as '\fBR1\fP-\fBR2\fP'. - -Regions that have a histogram configured can be grouped: in this case -the number of histogram bins and their bounds must match exactly. - -On success the group list and newly created \fBgroup_id\fP are -printed to stdout. - -The group metadata is stored with the first (lowest numbered) -\fBregion_id\fP in the group: deleting this region will also delete -the group and other group members will be returned to their prior -state. -. -.HP -.CMD_HELP -.br -Outputs a summary of the commands available, optionally including -the list of report fields. -. -.HP -.CMD_LIST -.br -List the statistics regions, areas, or groups registered on the device. -If the \fB\-\-allprograms\fP switch is given all regions will be listed -regardless of region program ID values. - -By default only regions and groups are included in list output. If -\fB\-v\fP or \fB\-\-verbose\fP is given the report will also include a -row of information for each configured group and for each area contained -in each region displayed. - -Regions that contain a single area are by default omitted from the -verbose list since their properties are identical to the area that they -contain - to view all regions regardless of the number of areas present -use \fB\-\-region\fP). To also view the areas contained within regions -use \fB\-\-area\fP. - -If \fB\-\-histogram\fP is given the report will include the bin count -and latency boundary values for any configured histograms. -.HP -.CMD_PRINT -.br -Print raw statistics counters for the specified region or for all -present regions. -. -.HP -.CMD_REPORT -.br -Start a report for the specified object or for all present objects. If -the count argument is specified, the report will repeat at a fixed -interval set by the \fB\-\-interval\fP option. The default interval is -one second. - -If the \fB\-\-allprograms\fP switch is given, all regions will be -listed, regardless of region program ID values. - -If the \fB\-\-histogram\fP is given the report will include the histogram -values and latency boundaries. - -If the \fB\-\-relative\fP is used the default histogram field displays -bin values as a percentage of the total number of I/Os. - -Object types (areas, regions and groups) to include in the report are -selected using the \fB\-\-area\fP, \fB\-\-region\fP, and \fB\-\-group\fP -options. -. -.HP -.CMD_UNGROUP -.br -Remove an existing group and return all the group's regions to their -original state. - -The group to be removed is specified using \fB\-\-groupid\fP. -.HP -.CMD_UPDATE_FILEMAP -.br -Update a group of \fBdmstats\fP regions specified by \fBgroup_id\fP, -that were previously created with \fB\-\-filemap\fP, either directly, -or by starting the monitoring daemon, \fBdmfilemapd\fP. - -This will add and remove regions to reflect changes in the allocated -extents of the file on-disk, since the time that it was crated or last -updated. - -Use of this command is not normally needed since the \fBdmfilemapd\fP -daemon will automatically monitor filemap groups and perform these -updates when required. - -If a filemapped group was created with \fB\-\-nomonitor\fP, or the -daemon has been killed, the \fBupdate_filemap\fP can be used to -manually force an update or start a new daemon. - -Use \fB\-\-nomonitor\fP to force a direct update and disable starting -the monitoring daemon. -. -.SH REGIONS, AREAS, AND GROUPS -. -The device-mapper statistics facility allows separate performance -counters to be maintained for arbitrary regions of devices. A region may -span any range: from a single sector to the whole device. A region may -be further sub-divided into a number of distinct areas (one or more), -each with its own counter set. In this case a summary value for the -entire region is also available for use in reports. - -In addition, one or more regions on one device can be combined into -a statistics group. Groups allow several regions to be aggregated and -reported as a single entity; counters for all regions and areas are -summed and used to report totals for all group members. Groups also -permit the assignment of an optional alias, allowing meaningful names -to be associated with sets of regions. - -The group metadata is stored with the first (lowest numbered) -\fBregion_id\fP in the group: deleting this region will also delete -the group and other group members will be returned to their prior -state. - -By default new regions span the entire device. The \fB\-\-start\fP and -\fB\-\-length\fP options allows a region of any size to be placed at any -location on the device. - -Using offsets it is possible to create regions that map individual -objects within a block device (for example: partitions, files in a file -system, or stripes or other structures in a RAID volume). Groups allow -several non-contiguous regions to be assembled together for reporting -and data aggregation. - -A region may be either divided into the specified number of equal-sized -areas, or into areas of the given size by specifying one of -\fB\-\-areas\fP or \fB\-\-areasize\fP when creating a region with the -\fBcreate\fP command. Depending on the size of the areas and the device -region the final area within the region may be smaller than requested. -.P -.B Region identifiers -.P -Each region is assigned an identifier when it is created that is used to -reference the region in subsequent operations. Region identifiers are -unique within a given device (including across different \fBprogram_id\fP -values). - -Depending on the sequence of create and delete operations, gaps may -exist in the sequence of \fBregion_id\fP values for a particular device. - -The \fBregion_id\fP should be treated as an opaque identifier used to -reference the region. -. -.P -.B Group identifiers -.P -Groups are also assigned an integer identifier at creation time; -like region identifiers, group identifiers are unique within the -containing device. - -The \fBgroup_id\fP should be treated as an opaque identifier used to -reference the group. -. -.SH FILE MAPPING -. -Using \fB\-\-filemap\fP, it is possible to create regions that -correspond to the extents of a file in the file system. This allows -IO statistics to be monitored on a per-file basis, for example to -observe large database files, virtual machine images, or other files -of interest. - -To be able to use file mapping, the file must be backed by a -device-mapper device, and in a file system that supports the FIEMAP -ioctl (and which returns data describing the physical location of -extents). This currently includes \fBxfs(5)\fP and \fBext4(5)\fP. - -By default the regions making up a file are placed together in a -group, and the group alias is set to the \fBbasename(3)\fP of the -file. This allows statistics to be reported for the file as a whole, -aggregating values for the regions making up the group. To see only -the whole file (group) when using the \fBlist\fP and \fBreport\fP -commands, use \fB\-\-group\fP. - -Since it is possible for the file to change after the initial -group of regions is created, the \fBupdate_filemap\fP command, and -\fBdmfilemapd\fP daemon are provided to update file mapped groups -either manually or automatically. -. -.P -.B File follow modes -.P -The file map monitoring daemon can monitor files in two distinct ways: -follow-inode mode, and follow-path mode. - -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. - -If follow-inode mode is used, the daemon will hold the file open, and -continue to update regions from the same file descriptor. This means -that the mapping will follow rename, move (within the same file -system), and unlink operations. This mode is useful if the file is -expected to be moved, renamed, or unlinked while it is being -monitored. - -In follow-inode mode, the daemon will exit once it detects that the -file has been unlinked and it is the last holder of a reference to it. - -If follow-path is used, the daemon will re-open the provided path on -each monitoring iteration. This means that the group will be updated -to reflect a new file being moved to the same path as the original -file. This mode is useful for files that are expected to be updated -via unlink and rename. - -In follow-path mode, the daemon will exit if the file is removed and -not replaced within a brief tolerance interval (one second). - -To stop the daemon, delete the group containing the mapped regions: -the daemon will automatically shut down. - -The daemon can also be safely killed at any time and the group kept: -if the file is still being allocated the mapping will become -progressively out-of-date as extents are added and removed (in this -case the daemon can be re-started or the group updated manually with -the \fBupdate_filemap\fP command). - -See the \fBcreate\fP command and \fB\-\-filemap\fP, \fB\-\-follow\fP, -and \fB\-\-nomonitor\fP options for further information. -. -.P -.B Limitations -.P -The daemon attempts to maintain good synchronisation between the file -extents and the regions contained in the group, however, since it 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 end-of-file (for example, the \fBdd\fP program). - -There is a further loss of events in that there is currently no way -to atomically resize a \fBdmstats\fP 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. -. -.SH REPORT FIELDS -. -The dmstats report provides several types of field that may be added to -the default field set, or used to create custom reports. - -All performance counters and metrics are calculated per-area. -. -.SS Derived metrics -. -A number of metrics fields are included that provide high level -performance indicators. These are based on the fields provided by the -conventional Linux iostat program and are derived from the basic counter -values provided by the kernel for each area. -.TP -.B reads_merged_per_sec -Reads merged per second. -.TP -.B writes_merged_per_sec -Writes merged per second. -.TP -.B reads_per_sec -Reads completed per second. -.TP -.B writes_per_sec -Writes completed per second. -.TP -.B read_size_per_sec -Size of data read per second. -.TP -.B write_size_per_sec -Size of data written per second. -.TP -.B avg_request_size -Average request size. -.TP -.B queue_size -Average queue size. -.TP -.B await -The average wait time for read and write operations. -.TP -.B r_await -The average wait time for read operations. -.TP -.B w_await -The average wait time for write operations. -.TP -.B throughput -The device throughput in operations per second. -.TP -.B service_time -The average service time (in milliseconds) for operations issued -to the device. -.TP -.B util -Percentage of CPU time during which I/O requests were issued to the -device (bandwidth utilization for the device). Device saturation occurs -when this value is close to 100%. -. -.SS Group, region and area meta fields -. -Meta fields provide information about the groups, regions, or areas that -the statistics values relate to. This includes the region and area -identifier, start, length, and counts, as well as the program ID and -user data values. -.TP -.B region_id -Region identifier. This is a non-negative integer returned by the kernel -when a statistics region is created. -.TP -.B region_start -The region start location. Display units are selected by the -\fB\-\-units\fP option. -.TP -.B region_len -The length of the region. Display units are selected by the -\fB\-\-units\fP option. -.TP -.B area_id -Area identifier. Area identifiers are assigned by the device-mapper -statistics library and uniquely identify each area within a region. Each -ID corresponds to a distinct set of performance counters for that area -of the statistics region. Area identifiers are always monotonically -increasing within a region so that higher ID values correspond to -greater sector addresses within the area and no gaps in the sequence of -identifiers exist. -.TP -.B area_start -The area start location. Display units are selected by the -\fB\-\-units\fP option. -.TP -.B area_len -The length of the area. Display units are selected by the -\fB\-\-units\fP option. -.TP -.B area_count -The number of areas in this region. -.TP -.B program_id -The program ID value associated with this region. -.TP -.B user_data -The user data value associated with this region. -.TP -.B group_id -Group identifier. This is a non-negative integer returned by the dmstats -\fBgroup\fP command when a statistics group is created. -.TP -.B interval_ns -The estimated interval over which the current counter values have -accumulated. The value is reported as an interger expressed in units -of nanoseconds. -.TP -.B interval -The estimated interval over which the current counter values have -accumulated. The value is reported as a real number in units of -seconds. -. -.SS Basic counters -. -Basic counters provide access to the raw counter data from the kernel, -allowing further processing to be carried out by another program. -.P -The kernel provides thirteen separate counters for each statistics -area. The first eleven of these match the counters provided in -/proc/diskstats or /sys/block/*/*/stat. The final pair provide separate -counters for read and write time. -.TP -.B read_count -Count of reads completed this interval. -.TP -.B reads_merged_count -Count of reads merged this interval. -.TP -.B read_sector_count -Count of 512 byte sectors read this interval. -.TP -.B read_time -Accumulated duration of all read requests (ns). -.TP -.B write_count -Count of writes completed this interval. -.TP -.B writes_merged_count -Count of writes merged this interval. -.TP -.B write_sector_count -Count of 512 byte sectors written this interval. -.TP -.B write_time -Accumulated duration of all write requests (ns). -.TP -.B in_progress_count -Count of requests currently in progress. -.TP -.B io_ticks -Nanoseconds spent servicing requests. -.TP -.B queue_ticks -This field is incremented at each I/O start, I/O completion, I/O merge, -or read of these stats by the number of I/Os in progress multiplied by -the number of milliseconds spent doing I/O since the last update of this -field. This can provide an easy measure of both I/O completion time and -the backlog that may be accumulating. -.TP -.B read_ticks -Nanoseconds spent servicing reads. -.TP -.B write_ticks -Nanoseconds spent servicing writes. -. -.SS Histogram fields -. -Histograms measure the frequency distribution of user specified I/O -latency intervals. Histogram bin boundaries are specified when a region -is created. -.P -A brief representation of the histogram values and latency intervals can -be included in the report using these fields. -.TP -.B hist_count -A list of the histogram counts for the current statistics area in order -of ascending latency value. Each value represents the number of I/Os -with latency times falling into that bin's time range during the sample -period. -.TP -.B hist_count_bounds -A list of the histogram counts for the current statistics area in order -of ascending latency value including bin boundaries: each count is -prefixed by the lower bound of the corresponding histogram bin. -.TP -.B hist_count_ranges -A list of the histogram counts for the current statistics area in order -of ascending latency value including bin boundaries: each count is -prefixed by both the lower and upper bounds of the corresponding -histogram bin. -.TP -.B hist_percent -A list of the relative histogram values for the current statistics area -in order of ascending latency value, expressed as a percentage. Each -value represents the proportion of I/Os with latency times falling into -that bin's time range during the sample period. -.TP -.B hist_percent_bounds -A list of the relative histogram values for the current statistics area -in order of ascending latency value, expressed as a percentage and -including bin boundaries. Each value represents the proportion of I/Os -with latency times falling into that bin's time range during the sample -period and is prefixed with the corresponding bin's lower bound. -.TP -.B hist_percent_ranges -A list of the relative histogram values for the current statistics area -in order of ascending latency value, expressed as a percentage and -including bin boundaries. Each value represents the proportion of I/Os -with latency times falling into that bin's time range during the sample -period and is prefixed with the corresponding bin's lower and upper -bounds. -.TP -.B hist_bounds -A list of the histogram boundary values for the current statistics area -in order of ascending latency value. The values are expressed in whole -units of seconds, miliseconds, microseconds or nanoseconds with a suffix -indicating the unit. -.TP -.B hist_ranges -A list of the histogram bin ranges for the current statistics area in -order of ascending latency value. The values are expressed as -"LOWER-UPPER" in whole units of seconds, miliseconds, microseconds or -nanoseconds with a suffix indicating the unit. -.TP -.B hist_bins -The number of latency histogram bins configured for the area. -. -.SH EXAMPLES -. -Create a whole-device region with one area on vg00/lvol1 -.br -# -.B dmstats create vg00/lvol1 -.br -vg00/lvol1: Created new region with 1 area(s) as region ID 0 -.P -Create a 32M region 1G into device d0 -.br -# -.B dmstats create \-\-start 1G \-\-length 32M d0 -.br -d0: Created new region with 1 area(s) as region ID 0 -.P -Create a whole-device region with 8 areas on every device -.br -.br -# -.B dmstats create \-\-areas 8 -.br -vg00-lvol1: Created new region with 8 area(s) as region ID 0 -.br -vg00-lvol2: Created new region with 8 area(s) as region ID 0 -.br -vg00-lvol3: Created new region with 8 area(s) as region ID 0 -.br -vg01-lvol0: Created new region with 8 area(s) as region ID 2 -.br -vg01-lvol1: Created new region with 8 area(s) as region ID 0 -.br -vg00-lvol2: Created new region with 8 area(s) as region ID 1 -.P -Delete all regions on all devices -.br -.br -# -.B dmstats delete \-\-alldevices \-\-allregions -.P -Create a whole-device region with areas 10GiB in size on vg00/lvol1 -using dmsetup -.br -.br -# -.B dmsetup stats create \-\-areasize 10G vg00/lvol1 -.br -vg00-lvol1: Created new region with 5 area(s) as region ID 1 -.P -Create a 1GiB region with 16 areas at the start of vg00/lvol1 -.br -# -.B dmstats create \-\-start 0 \-\-len 1G \-\-areas=16 vg00/lvol1 -.br -vg00-lvol1: Created new region with 16 area(s) as region ID 0 -.P -List the statistics regions registered on vg00/lvol1 -.br -# -.B dmstats list vg00/lvol1 -.br -Name RgID RStart RSize #Areas ASize ProgID -.br -vg00-lvol1 0 0 61.00g 1 61.00g dmstats -.br -vg00-lvol1 1 61.00g 19.20g 1 19.20g dmstats -.br -vg00-lvol1 2 80.20g 2.14g 1 2.14g dmstats -.P -Display five statistics reports for vg00/lvol1 at an interval of one second -.br -.br -# -.B dmstats report \-\-interval 1 \-\-count 5 vg00/lvol1 -.br -# -.B dmstats report -.br -Name RgID ArID AStart ASize RRqM/s WRqM/s R/s W/s RSz/s WSz/s AvRqSz QSize Util% AWait RdAWa WrAWa -.br -vg_hex-lv_home 0 0 0 61.00g 0.00 0.00 0.00 218.00 0 1.04m 4.50k 2.97 81.70 13.62 0.00 13.62 -.br -vg_hex-lv_home 1 0 61.00g 19.20g 0.00 0.00 0.00 5.00 0 548.00k 109.50k 0.14 11.00 27.40 0.00 27.40 -.br -vg_hex-lv_home 2 0 80.20g 2.14g 0.00 0.00 0.00 14.00 0 1.15m 84.00k 0.39 18.70 27.71 0.00 27.71 -.P -Create one region for reach target contained in device vg00/lvol1 -.br -.br -# -.B dmstats create \-\-segments vg00/lvol1 -.br -vg00-lvol1: Created new region with 1 area(s) as region ID 0 -.br -vg00-lvol1: Created new region with 1 area(s) as region ID 1 -.br -vg00-lvol1: Created new region with 1 area(s) as region ID 2 -.P -Create regions mapping each file in the directory images/ and place -them into separate groups, each named after the corresponding file -.br -# -.B dmstats create --filemap images/* -.br -images/vm1.qcow2: Created new group with 87 region(s) as group ID 0. -.br -images/vm1-1.qcow2: Created new group with 8 region(s) as group ID 87. -.br -images/vm2.qcow2: Created new group with 11 region(s) as group ID 95. -.br -images/vm2-1.qcow2: Created new group with 1454 region(s) as group ID 106. -.br -images/vm3.img: Created new group with 2 region(s) as group ID 1560. -.P -Print raw counters for region 4 on device d0 -.br -# -.B dmstats print \-\-regionid 4 d0 -.br -2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41 -. -.SH AUTHORS -. -Bryn M. Reeves -. -.SH SEE ALSO -. -.BR dmsetup (8) - -LVM2 resource page: https://www.sourceware.org/lvm2/ -.br -Device-mapper resource page: http://sources.redhat.com/dm/ -.br - -Device-mapper statistics kernel documentation -.br -.I Documentation/device-mapper/statistics.txt diff --git a/man/dmstats.8_main b/man/dmstats.8_main new file mode 100644 index 0000000..682f01d --- /dev/null +++ b/man/dmstats.8_main @@ -0,0 +1,1284 @@ +.TH DMSTATS 8 "Jun 23 2016" "Linux" "MAINTENANCE COMMANDS" + +.de OPT_PROGRAMS +. RB \%[ \-\-allprograms | \-\-programid +. IR id ] +.. +. +.de OPT_REGIONS +. RB \%[ \-\-allregions | \-\-regionid +. IR id ] +.. +.de OPT_OBJECTS +. RB [ \-\-area ] +. RB [ \-\-region ] +. RB [ \-\-group ] +.. +.de OPT_FOREGROUND +. RB [ \-\-foreground ] +.. +. +.\" Print units suffix, use with arg to print human +.\" man2html can't handle too many changes per command +.de UNITS +. BR b | B | s | S | k | K | m | M | \c +. BR g | G | t | T | p | P | e | E ] +.. +. +.\" Print help text for units, use with arg to print human +.de HELP_UNITS +. RB ( b )ytes, +. RB ( s )ectors, +. RB ( k )ilobytes, +. RB ( m )egabytes, +. RB ( g )igabytes, +. RB ( t )erabytes, +. RB ( p )etabytes, +. RB ( e )xabytes. +. nop Capitalise to use multiples of 1000 (S.I.) instead of 1024. +.. +. +.SH NAME +. +dmstats \(em device-mapper statistics management +. +.SH SYNOPSIS +. +.B dmsetup +.B stats +.I command +[OPTIONS] +.sp +. +.PD 0 +.HP +.B dmstats +.de CMD_COMMAND +. ad l +. IR command +. IR device_name " |" +. BR \-\-major +. IR major +. BR \-\-minor +. IR minor " |" +. BR \-u | \-\-uuid +. IR uuid +. RB \%[ \-v | \-\-verbose] +. ad b +.. +.CMD_COMMAND +. +.HP +.B dmstats +.de CMD_CLEAR +. ad l +. BR clear +. IR device_name +. OPT_PROGRAMS +. OPT_REGIONS +. ad b +.. +.CMD_CLEAR +. +.HP +.B dmstats +.de CMD_CREATE +. ad l +. BR create +. IR device_name... | file_path... | \fB\-\-alldevices +. RB [ \-\-areas +. IR nr_areas | \fB\-\-areasize +. IR area_size ] +. RB [ \-\-bounds +. IR \%histogram_boundaries ] +. RB [ \-\-filemap ] +. RB [ \-\-follow +. IR follow_mode ] +. OPT_FOREGROUND +. RB [ \-\-nomonitor ] +. RB [ \-\-nogroup ] +. RB [ \-\-precise ] +. RB [ \-\-start +. IR start_sector +. BR \-\-length +. IR length | \fB\-\-segments ] +. RB \%[ \-\-userdata +. IR user_data ] +. RB [ \-\-programid +. IR id ] +. ad b +.. +.CMD_CREATE +. +.HP +.B dmstats +.de CMD_DELETE +. ad l +. BR delete +. IR device_name | \fB\-\-alldevices +. OPT_PROGRAMS +. OPT_REGIONS +. ad b +.. +.CMD_DELETE +. +.HP +.B dmstats +.de CMD_GROUP +. ad l +. BR group +. RI [ device_name | \fB\-\-alldevices ] +. RB [ \-\-alias +. IR name ] +. RB [ \-\-regions +. IR regions ] +. ad b +.. +.CMD_GROUP +.HP +.B dmstats +.de CMD_HELP +. ad l +. BR help +. RB [ \-c | \-C | \-\-columns ] +. ad b +.. +.CMD_HELP +. +.HP +.B dmstats +.de CMD_LIST +. ad l +. BR list +. RI [ device_name ] +. RB [ \-\-histogram ] +. OPT_PROGRAMS +. RB [ \-\-units +. IR units ] +. OPT_OBJECTS +. RB \%[ \-\-nosuffix ] +. RB [ \-\-notimesuffix ] +. RB \%[ \-v | \-\-verbose] +. ad b +.. +.CMD_LIST +. +.HP +.B dmstats +.de CMD_PRINT +. ad l +. BR print +. RI [ device_name ] +. RB [ \-\-clear ] +. OPT_PROGRAMS +. OPT_REGIONS +. ad b +.. +.CMD_PRINT +. +.HP +.B dmstats +.de CMD_REPORT +. ad l +. BR report +. RI [ device_name ] +. RB [ \-\-interval +. IR seconds ] +. RB [ \-\-count +. IR count ] +. RB [ \-\-units +. IR units ] +. RB [ \-\-histogram ] +. OPT_PROGRAMS +. OPT_REGIONS +. OPT_OBJECTS +. RB [ \-O | \-\-sort +. IR sort_fields ] +. RB [ \-S | \-\-select +. IR selection ] +. RB [ \-\-units +. IR units ] +. RB [ \-\-nosuffix ] +. RB \%[ \-\-notimesuffix ] +. ad b +.. +.CMD_REPORT +.HP +.B dmstats +.de CMD_UNGROUP +. ad l +. BR ungroup +. RI [ device_name | \fB\-\-alldevices ] +. RB [ \-\-groupid +. IR id ] +. ad b +.. +.CMD_UNGROUP +.HP +.B dmstats +.de CMD_UPDATE_FILEMAP +. ad l +. BR update_filemap +. IR file_path +. RB [ \-\-groupid +. IR id ] +. RB [ \-\-follow +. IR follow_mode ] +. OPT_FOREGROUND +. ad b +.. +.CMD_UPDATE_FILEMAP +. +.PD +.ad b +. +.SH DESCRIPTION +. +The dmstats program manages IO statistics regions for devices that use +the device-mapper driver. Statistics regions may be created, deleted, +listed and reported on using the tool. + +The first argument to dmstats is a \fIcommand\fP. + +The second argument is the \fIdevice name\fP, +\fIuuid\fP or \fImajor\fP and \fIminor\fP numbers. + +Further options permit the selection of regions, output format +control, and reporting behaviour. + +When no device argument is given dmstats will by default operate on all +device-mapper devices present. The \fBcreate\fP and \fBdelete\fP +commands require the use of \fB\-\-alldevices\fP when used in this way. +. +.SH OPTIONS +. +.HP +.BR \-\-alias +.IR name +.br +Specify an alias name for a group. +. +.HP +.BR \-\-alldevices +.br +If no device arguments are given allow operation on all devices when +creating or deleting regions. +. +.HP +.BR \-\-allprograms +.br +Include regions from all program IDs for list and report operations. +.br +.HP +.BR \-\-allregions +.br +Include all present regions for commands that normally accept a single +region identifier. +. +.HP +.BR \-\-area +.br +When peforming a list or report, include objects of type area in the +results. +. +.HP +.BR \-\-areas +.IR nr_areas +.br +Specify the number of statistics areas to create within a new region. +. +.HP +.BR \-\-areasize +.IR area_size \c +.RB [ \c +.UNITS +.br +Specify the size of areas into which a new region should be divided. An +optional suffix selects units of: +.HELP_UNITS +. +.HP +.BR \-\-clear +.br +When printing statistics counters, also atomically reset them to zero. +. +.HP +.BR \-\-count +.IR count +.br +Specify the iteration count for repeating reports. If the count +argument is zero reports will continue to repeat until interrupted. +. +.HP +.BR \-\-group +.br +When peforming a list or report, include objects of type group in the +results. +. +.HP +.BR \-\-filemap +.br +Instead of creating regions on a device as specified by command line +options, open the file found at each \fBfile_path\fP argument, and +create regions corresponding to the locations of the on-disk extents +allocated to the file(s). +. +.HP +.BR \-\-nomonitor +.br +Disable the \fBdmfilemapd\fP daemon when creating new file mapped +groups. Normally the device-mapper filemap monitoring daemon, +\fBdmfilemapd\fP, is started for each file mapped group to update the +set of regions as the file changes on-disk: use of this option +disables this behaviour. + +Regions in the group may still be updated with the +\fBupdate_filemap\fP command, or by starting the daemon manually. +. +.HP +.BR \-\-follow +.IR follow_mode +.br +Specify the \fBdmfilemapd\fP file following mode. 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. + +The \fBfollow_mode\fP argument is either "inode", for follow-inode +mode, or "path", for follow-path. + +If follow-inode mode is used, the daemon will hold the file open, and +continue to update regions from the same file descriptor. This means +that the mapping will follow rename, move (within the same file +system), and unlink operations. This mode is useful if the file is +expected to be moved, renamed, or unlinked while it is being +monitored. + +In follow-inode mode, the daemon will exit once it detects that the +file has been unlinked and it is the last holder of a reference to it. + +If follow-path is used, the daemon will re-open the provided path on +each monitoring iteration. This means that the group will be updated +to reflect a new file being moved to the same path as the original +file. This mode is useful for files that are expected to be updated +via unlink and rename. + +In follow-path mode, the daemon will exit if the file is removed and +not replaced within a brief tolerance interval. + +In either mode, the daemon exits automatically if the monitored group +is removed. +. +.HP +.BR \-\-foreground +.br +Specify that the \fBdmfilemapd\fP daemon should run in the foreground. +The daemon will not fork into the background, and will replace the +\fBdmstats\fP command that started it. +. +.HP +.BR \-\-groupid +.IR id +.br +Specify the group to operate on. +. +.HP +.BR \-\-bounds +.IR histogram_boundaries \c +.RB [ ns | us | ms | s ] +.br +Specify the boundaries of a latency histogram to be tracked for the +region as a comma separated list of latency values. Latency values are +given in nanoseconds. An optional unit suffix of +.BR ns , +.BR us , +.BR ms , +or \fBs\fP may be given after each value to specify units of +nanoseconds, microseconds, miliseconds or seconds respectively. +. +.HP +.BR \-\-histogram +.br +When used with the \fBreport\fP and \fBlist\fP commands select default +fields that emphasize latency histogram data. +. +.HP +.BR \-\-interval +.IR seconds +.br +Specify the interval in seconds between successive iterations for +repeating reports. If \fB\-\-interval\fP is specified but +\fB\-\-count\fP is not, +reports will continue to repeat until interrupted. +. +.HP +.BR \-\-length +.IR length \c +.RB [ \c +.UNITS +.br +Specify the length of a new statistics region in sectors. An optional +suffix selects units of: +.HELP_UNITS +. +.HP +.BR \-j | \-\-major +.IR major +.br +Specify the major number. +. +.HP +.BR \-m | \-\-minor +.IR minor +.br +Specify the minor number. +. +.HP +.BR \-\-nogroup +.br +When creating regions mapping the extents of a file in the file +system, do not create a group or set an alias. +. +.HP +.BR \-\-nosuffix +.br +Suppress the suffix on output sizes. Use with \fB\-\-units\fP +(except h and H) if processing the output. +. +.HP +.BR \-\-notimesuffix +.br +Suppress the suffix on output time values. Histogram boundary values +will be reported in units of nanoseconds. +. +.HP +.BR \-o | \-\-options +.br +Specify which report fields to display. +. +.HP +.BR \-O | \-\-sort +.IR sort_fields +.br +Sort output according to the list of fields given. Precede any +sort field with '\fB-\fP' for a reverse sort on that column. +. +.HP +.BR \-\-precise +.br +Attempt to use nanosecond precision counters when creating new +statistics regions. +. +.HP +.BR \-\-programid +.IR id +.br +Specify a program ID string. When creating new statistics regions this +string is stored with the region. Subsequent operations may supply a +program ID in order to select only regions with a matching value. The +default program ID for dmstats-managed regions is "dmstats". +. +.HP +.BR \-\-region +.br +When peforming a list or report, include objects of type region in the +results. +. +.HP +.BR \-\-regionid +.IR id +.br +Specify the region to operate on. +. +.HP +.BR \-\-regions +.IR region_list +.br +Specify a list of regions to group. The group list is a comma-separated +list of region identifiers. Continuous sequences of identifiers may be +expressed as a hyphen separated range, for example: '1-10'. +. +.HP +.BR \-\-relative +.br +If displaying the histogram report show relative (percentage) values +instead of absolute counts. +. +.HP +.BR \-S | \-\-select +.IR selection +.br +Display only rows that match \fIselection\fP criteria. All rows with the +additional "selected" column (\fB\-o selected\fP) showing 1 if the row matches +the \fIselection\fP and 0 otherwise. The selection criteria are defined by +specifying column names and their valid values while making use of +supported comparison operators. +. +.HP +.BR \-\-start +.IR start \c +.RB [ \c +.UNITS +.br +Specify the start offset of a new statistics region in sectors. An +optional suffix selects units of: +.HELP_UNITS +. +.HP +.BR \-\-segments +.br +When used with \fBcreate\fP, create a new statistics region for each +target contained in the given device(s). This causes a separate region +to be allocated for each segment of the device. + +The newly created regions are automatically placed into a group unless +the \fB\-\-nogroup\fP option is given. When grouping is enabled a group +alias may be specified using the \fB\-\-alias\fP option. +. +.HP +.BR \-\-units +.RI [ units ] \c +.RB [ h | H | \c +.UNITS +.br +Set the display units for report output. +All sizes are output in these units: +.RB ( h )uman-readable, +.HELP_UNITS +Can also specify custom units e.g. \fB\-\-units\ 3M\fP. +. +.HP +.BR \-\-userdata +.IR user_data +.br +Specify user data (a word) to be stored with a new region. The value +is added to any internal auxilliary data (for example, group +information), and stored with the region in the aux_data field provided +by the kernel. Whitespace is not permitted. +. +.HP +.BR \-u | \-\-uuid +.br +Specify the uuid. +. +.HP +.BR \-v | \-\-verbose " [" \-v | \-\-verbose ] +.br +Produce additional output. +. +.SH COMMANDS +. +.HP +.CMD_CLEAR +.br +Instructs the kernel to clear statistics counters for the speficied +regions (with the exception of in-flight IO counters). +. +.HP +.CMD_CREATE +.br +Creates one or more new statistics regions on the specified device(s). + +The region will span the entire device unless \fB\-\-start\fP and +\fB\-\-length\fP or \fB\-\-segments\fP are given. The \fB\-\-start\fP an +\fB\-\-length\fP options allow a region of arbitrary length to be placed +at an arbitrary offset into the device. The \fB\-\-segments\fP option +causes a new region to be created for each target in the corresponding +device-mapper device's table. + +If the \fB\-\-precise\fP option is used the command will attempt to +create a region using nanosecond precision counters. + +If \fB\-\-bounds\fP is given a latency histogram will be tracked for +the new region. The boundaries of the histogram bins are given as a +comma separated list of latency values. There is an implicit lower bound +of zero on the first bin and an implicit upper bound of infinity (or the +configured interval duration) on the final bin. + +Latencies are given in nanoseconds. An optional unit suffix of ns, us, +ms, or s may be given after each value to specify units of nanoseconds, +microseconds, miliseconds or seconds respectively, so for example, 10ms +is equivalent to 10000000. Latency values with a precision of less than +one milisecond can only be used when precise timestamps are enabled: if +\fB\-\-precise\fP is not given and values less than one milisecond are +used it will be enabled automatically. + +An optional \fBprogram_id\fP or \fBuser_data\fP string may be associated +with the region. A \fBprogram_id\fP may then be used to select regions +for subsequent list, print, and report operations. The \fBuser_data\fP +stores an arbitrary string and is not used by dmstats or the +device-mapper kernel statistics subsystem. + +By default dmstats creates regions with a \fBprogram_id\fP of +"dmstats". + +On success the \fBregion_id\fP of the newly created region is printed +to stdout. + +If the \fB\-\-filemap\fP option is given with a regular file, or list +of files, as the \fBfile_path\fP argument, instead of creating regions +with parameters specified on the command line, \fBdmstats\fP will open +the files located at \fBfile_path\fP and create regions corresponding to +the physical extents allocated to the file. This can be used to monitor +statistics for individual files in the file system, for example, virtual +machine images, swap areas, or large database files. + +To work with the \fB\-\-filemap\fP option, files must be located on a +local file system, backed by a device-mapper device, that supports +physical extent data using the FIEMAP ioctl (Ext4 and XFS for e.g.). + +By default regions that map a file are placed into a group and the +group alias is set to the basename of the file. This behaviour can be +overridden with the \fB\-\-alias\fP and \fB\-\-nogroup\fP options. + +Creating a group that maps a file automatically starts a daemon, +\fBdmfilemapd\fP to monitor the file and update the mapping as the +extents allocated to the file change. This behaviour can be disabled +using the \fB\-\-nomonitor\fP option. + +Use the \fB\-\-group\fP option to only display information for groups +when listing and reporting. +. +.HP +.CMD_DELETE +.br +Delete the specified statistics region. All counters and resources used +by the region are released and the region will not appear in the output +of subsequent list, print, or report operations. + +All regions registered on a device may be removed using +\fB\-\-allregions\fP. + +To remove all regions on all devices both \fB\-\-allregions\fP and +\fB\-\-alldevices\fP must be used. + +If a \fB\-\-groupid\fP is given instead of a \fB\-\-regionid\fP the +command will attempt to delete the group and all regions that it +contains. + +If a deleted region is the first member of a group of regions the group +will also be removed. +. +.HP +.CMD_GROUP +.br +Combine one or more statistics regions on the specified device into a +group. + +The list of regions to be grouped is specified with \fB\-\-regions\fP +and an optional alias may be assigned with \fB\-\-alias\fP. The set of +regions is given as a comma-separated list of region identifiers. A +continuous range of identifers spanning from \fBR1\fP to \fBR2\fP may +be expressed as '\fBR1\fP-\fBR2\fP'. + +Regions that have a histogram configured can be grouped: in this case +the number of histogram bins and their bounds must match exactly. + +On success the group list and newly created \fBgroup_id\fP are +printed to stdout. + +The group metadata is stored with the first (lowest numbered) +\fBregion_id\fP in the group: deleting this region will also delete +the group and other group members will be returned to their prior +state. +. +.HP +.CMD_HELP +.br +Outputs a summary of the commands available, optionally including +the list of report fields. +. +.HP +.CMD_LIST +.br +List the statistics regions, areas, or groups registered on the device. +If the \fB\-\-allprograms\fP switch is given all regions will be listed +regardless of region program ID values. + +By default only regions and groups are included in list output. If +\fB\-v\fP or \fB\-\-verbose\fP is given the report will also include a +row of information for each configured group and for each area contained +in each region displayed. + +Regions that contain a single area are by default omitted from the +verbose list since their properties are identical to the area that they +contain - to view all regions regardless of the number of areas present +use \fB\-\-region\fP). To also view the areas contained within regions +use \fB\-\-area\fP. + +If \fB\-\-histogram\fP is given the report will include the bin count +and latency boundary values for any configured histograms. +.HP +.CMD_PRINT +.br +Print raw statistics counters for the specified region or for all +present regions. +. +.HP +.CMD_REPORT +.br +Start a report for the specified object or for all present objects. If +the count argument is specified, the report will repeat at a fixed +interval set by the \fB\-\-interval\fP option. The default interval is +one second. + +If the \fB\-\-allprograms\fP switch is given, all regions will be +listed, regardless of region program ID values. + +If the \fB\-\-histogram\fP is given the report will include the histogram +values and latency boundaries. + +If the \fB\-\-relative\fP is used the default histogram field displays +bin values as a percentage of the total number of I/Os. + +Object types (areas, regions and groups) to include in the report are +selected using the \fB\-\-area\fP, \fB\-\-region\fP, and \fB\-\-group\fP +options. +. +.HP +.CMD_UNGROUP +.br +Remove an existing group and return all the group's regions to their +original state. + +The group to be removed is specified using \fB\-\-groupid\fP. +.HP +.CMD_UPDATE_FILEMAP +.br +Update a group of \fBdmstats\fP regions specified by \fBgroup_id\fP, +that were previously created with \fB\-\-filemap\fP, either directly, +or by starting the monitoring daemon, \fBdmfilemapd\fP. + +This will add and remove regions to reflect changes in the allocated +extents of the file on-disk, since the time that it was crated or last +updated. + +Use of this command is not normally needed since the \fBdmfilemapd\fP +daemon will automatically monitor filemap groups and perform these +updates when required. + +If a filemapped group was created with \fB\-\-nomonitor\fP, or the +daemon has been killed, the \fBupdate_filemap\fP can be used to +manually force an update or start a new daemon. + +Use \fB\-\-nomonitor\fP to force a direct update and disable starting +the monitoring daemon. +. +.SH REGIONS, AREAS, AND GROUPS +. +The device-mapper statistics facility allows separate performance +counters to be maintained for arbitrary regions of devices. A region may +span any range: from a single sector to the whole device. A region may +be further sub-divided into a number of distinct areas (one or more), +each with its own counter set. In this case a summary value for the +entire region is also available for use in reports. + +In addition, one or more regions on one device can be combined into +a statistics group. Groups allow several regions to be aggregated and +reported as a single entity; counters for all regions and areas are +summed and used to report totals for all group members. Groups also +permit the assignment of an optional alias, allowing meaningful names +to be associated with sets of regions. + +The group metadata is stored with the first (lowest numbered) +\fBregion_id\fP in the group: deleting this region will also delete +the group and other group members will be returned to their prior +state. + +By default new regions span the entire device. The \fB\-\-start\fP and +\fB\-\-length\fP options allows a region of any size to be placed at any +location on the device. + +Using offsets it is possible to create regions that map individual +objects within a block device (for example: partitions, files in a file +system, or stripes or other structures in a RAID volume). Groups allow +several non-contiguous regions to be assembled together for reporting +and data aggregation. + +A region may be either divided into the specified number of equal-sized +areas, or into areas of the given size by specifying one of +\fB\-\-areas\fP or \fB\-\-areasize\fP when creating a region with the +\fBcreate\fP command. Depending on the size of the areas and the device +region the final area within the region may be smaller than requested. +.P +.B Region identifiers +.P +Each region is assigned an identifier when it is created that is used to +reference the region in subsequent operations. Region identifiers are +unique within a given device (including across different \fBprogram_id\fP +values). + +Depending on the sequence of create and delete operations, gaps may +exist in the sequence of \fBregion_id\fP values for a particular device. + +The \fBregion_id\fP should be treated as an opaque identifier used to +reference the region. +. +.P +.B Group identifiers +.P +Groups are also assigned an integer identifier at creation time; +like region identifiers, group identifiers are unique within the +containing device. + +The \fBgroup_id\fP should be treated as an opaque identifier used to +reference the group. +. +.SH FILE MAPPING +. +Using \fB\-\-filemap\fP, it is possible to create regions that +correspond to the extents of a file in the file system. This allows +IO statistics to be monitored on a per-file basis, for example to +observe large database files, virtual machine images, or other files +of interest. + +To be able to use file mapping, the file must be backed by a +device-mapper device, and in a file system that supports the FIEMAP +ioctl (and which returns data describing the physical location of +extents). This currently includes \fBxfs(5)\fP and \fBext4(5)\fP. + +By default the regions making up a file are placed together in a +group, and the group alias is set to the \fBbasename(3)\fP of the +file. This allows statistics to be reported for the file as a whole, +aggregating values for the regions making up the group. To see only +the whole file (group) when using the \fBlist\fP and \fBreport\fP +commands, use \fB\-\-group\fP. + +Since it is possible for the file to change after the initial +group of regions is created, the \fBupdate_filemap\fP command, and +\fBdmfilemapd\fP daemon are provided to update file mapped groups +either manually or automatically. +. +.P +.B File follow modes +.P +The file map monitoring daemon can monitor files in two distinct ways: +follow-inode mode, and follow-path mode. + +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. + +If follow-inode mode is used, the daemon will hold the file open, and +continue to update regions from the same file descriptor. This means +that the mapping will follow rename, move (within the same file +system), and unlink operations. This mode is useful if the file is +expected to be moved, renamed, or unlinked while it is being +monitored. + +In follow-inode mode, the daemon will exit once it detects that the +file has been unlinked and it is the last holder of a reference to it. + +If follow-path is used, the daemon will re-open the provided path on +each monitoring iteration. This means that the group will be updated +to reflect a new file being moved to the same path as the original +file. This mode is useful for files that are expected to be updated +via unlink and rename. + +In follow-path mode, the daemon will exit if the file is removed and +not replaced within a brief tolerance interval (one second). + +To stop the daemon, delete the group containing the mapped regions: +the daemon will automatically shut down. + +The daemon can also be safely killed at any time and the group kept: +if the file is still being allocated the mapping will become +progressively out-of-date as extents are added and removed (in this +case the daemon can be re-started or the group updated manually with +the \fBupdate_filemap\fP command). + +See the \fBcreate\fP command and \fB\-\-filemap\fP, \fB\-\-follow\fP, +and \fB\-\-nomonitor\fP options for further information. +. +.P +.B Limitations +.P +The daemon attempts to maintain good synchronisation between the file +extents and the regions contained in the group, however, since it 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 end-of-file (for example, the \fBdd\fP program). + +There is a further loss of events in that there is currently no way +to atomically resize a \fBdmstats\fP 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. +. +.SH REPORT FIELDS +. +The dmstats report provides several types of field that may be added to +the default field set, or used to create custom reports. + +All performance counters and metrics are calculated per-area. +. +.SS Derived metrics +. +A number of metrics fields are included that provide high level +performance indicators. These are based on the fields provided by the +conventional Linux iostat program and are derived from the basic counter +values provided by the kernel for each area. +.TP +.B reads_merged_per_sec +Reads merged per second. +.TP +.B writes_merged_per_sec +Writes merged per second. +.TP +.B reads_per_sec +Reads completed per second. +.TP +.B writes_per_sec +Writes completed per second. +.TP +.B read_size_per_sec +Size of data read per second. +.TP +.B write_size_per_sec +Size of data written per second. +.TP +.B avg_request_size +Average request size. +.TP +.B queue_size +Average queue size. +.TP +.B await +The average wait time for read and write operations. +.TP +.B r_await +The average wait time for read operations. +.TP +.B w_await +The average wait time for write operations. +.TP +.B throughput +The device throughput in operations per second. +.TP +.B service_time +The average service time (in milliseconds) for operations issued +to the device. +.TP +.B util +Percentage of CPU time during which I/O requests were issued to the +device (bandwidth utilization for the device). Device saturation occurs +when this value is close to 100%. +. +.SS Group, region and area meta fields +. +Meta fields provide information about the groups, regions, or areas that +the statistics values relate to. This includes the region and area +identifier, start, length, and counts, as well as the program ID and +user data values. +.TP +.B region_id +Region identifier. This is a non-negative integer returned by the kernel +when a statistics region is created. +.TP +.B region_start +The region start location. Display units are selected by the +\fB\-\-units\fP option. +.TP +.B region_len +The length of the region. Display units are selected by the +\fB\-\-units\fP option. +.TP +.B area_id +Area identifier. Area identifiers are assigned by the device-mapper +statistics library and uniquely identify each area within a region. Each +ID corresponds to a distinct set of performance counters for that area +of the statistics region. Area identifiers are always monotonically +increasing within a region so that higher ID values correspond to +greater sector addresses within the area and no gaps in the sequence of +identifiers exist. +.TP +.B area_start +The area start location. Display units are selected by the +\fB\-\-units\fP option. +.TP +.B area_len +The length of the area. Display units are selected by the +\fB\-\-units\fP option. +.TP +.B area_count +The number of areas in this region. +.TP +.B program_id +The program ID value associated with this region. +.TP +.B user_data +The user data value associated with this region. +.TP +.B group_id +Group identifier. This is a non-negative integer returned by the dmstats +\fBgroup\fP command when a statistics group is created. +.TP +.B interval_ns +The estimated interval over which the current counter values have +accumulated. The value is reported as an interger expressed in units +of nanoseconds. +.TP +.B interval +The estimated interval over which the current counter values have +accumulated. The value is reported as a real number in units of +seconds. +. +.SS Basic counters +. +Basic counters provide access to the raw counter data from the kernel, +allowing further processing to be carried out by another program. +.P +The kernel provides thirteen separate counters for each statistics +area. The first eleven of these match the counters provided in +/proc/diskstats or /sys/block/*/*/stat. The final pair provide separate +counters for read and write time. +.TP +.B read_count +Count of reads completed this interval. +.TP +.B reads_merged_count +Count of reads merged this interval. +.TP +.B read_sector_count +Count of 512 byte sectors read this interval. +.TP +.B read_time +Accumulated duration of all read requests (ns). +.TP +.B write_count +Count of writes completed this interval. +.TP +.B writes_merged_count +Count of writes merged this interval. +.TP +.B write_sector_count +Count of 512 byte sectors written this interval. +.TP +.B write_time +Accumulated duration of all write requests (ns). +.TP +.B in_progress_count +Count of requests currently in progress. +.TP +.B io_ticks +Nanoseconds spent servicing requests. +.TP +.B queue_ticks +This field is incremented at each I/O start, I/O completion, I/O merge, +or read of these stats by the number of I/Os in progress multiplied by +the number of milliseconds spent doing I/O since the last update of this +field. This can provide an easy measure of both I/O completion time and +the backlog that may be accumulating. +.TP +.B read_ticks +Nanoseconds spent servicing reads. +.TP +.B write_ticks +Nanoseconds spent servicing writes. +. +.SS Histogram fields +. +Histograms measure the frequency distribution of user specified I/O +latency intervals. Histogram bin boundaries are specified when a region +is created. +.P +A brief representation of the histogram values and latency intervals can +be included in the report using these fields. +.TP +.B hist_count +A list of the histogram counts for the current statistics area in order +of ascending latency value. Each value represents the number of I/Os +with latency times falling into that bin's time range during the sample +period. +.TP +.B hist_count_bounds +A list of the histogram counts for the current statistics area in order +of ascending latency value including bin boundaries: each count is +prefixed by the lower bound of the corresponding histogram bin. +.TP +.B hist_count_ranges +A list of the histogram counts for the current statistics area in order +of ascending latency value including bin boundaries: each count is +prefixed by both the lower and upper bounds of the corresponding +histogram bin. +.TP +.B hist_percent +A list of the relative histogram values for the current statistics area +in order of ascending latency value, expressed as a percentage. Each +value represents the proportion of I/Os with latency times falling into +that bin's time range during the sample period. +.TP +.B hist_percent_bounds +A list of the relative histogram values for the current statistics area +in order of ascending latency value, expressed as a percentage and +including bin boundaries. Each value represents the proportion of I/Os +with latency times falling into that bin's time range during the sample +period and is prefixed with the corresponding bin's lower bound. +.TP +.B hist_percent_ranges +A list of the relative histogram values for the current statistics area +in order of ascending latency value, expressed as a percentage and +including bin boundaries. Each value represents the proportion of I/Os +with latency times falling into that bin's time range during the sample +period and is prefixed with the corresponding bin's lower and upper +bounds. +.TP +.B hist_bounds +A list of the histogram boundary values for the current statistics area +in order of ascending latency value. The values are expressed in whole +units of seconds, miliseconds, microseconds or nanoseconds with a suffix +indicating the unit. +.TP +.B hist_ranges +A list of the histogram bin ranges for the current statistics area in +order of ascending latency value. The values are expressed as +"LOWER-UPPER" in whole units of seconds, miliseconds, microseconds or +nanoseconds with a suffix indicating the unit. +.TP +.B hist_bins +The number of latency histogram bins configured for the area. +. +.SH EXAMPLES +. +Create a whole-device region with one area on vg00/lvol1 +.br +# +.B dmstats create vg00/lvol1 +.br +vg00/lvol1: Created new region with 1 area(s) as region ID 0 +.P +Create a 32M region 1G into device d0 +.br +# +.B dmstats create \-\-start 1G \-\-length 32M d0 +.br +d0: Created new region with 1 area(s) as region ID 0 +.P +Create a whole-device region with 8 areas on every device +.br +.br +# +.B dmstats create \-\-areas 8 +.br +vg00-lvol1: Created new region with 8 area(s) as region ID 0 +.br +vg00-lvol2: Created new region with 8 area(s) as region ID 0 +.br +vg00-lvol3: Created new region with 8 area(s) as region ID 0 +.br +vg01-lvol0: Created new region with 8 area(s) as region ID 2 +.br +vg01-lvol1: Created new region with 8 area(s) as region ID 0 +.br +vg00-lvol2: Created new region with 8 area(s) as region ID 1 +.P +Delete all regions on all devices +.br +.br +# +.B dmstats delete \-\-alldevices \-\-allregions +.P +Create a whole-device region with areas 10GiB in size on vg00/lvol1 +using dmsetup +.br +.br +# +.B dmsetup stats create \-\-areasize 10G vg00/lvol1 +.br +vg00-lvol1: Created new region with 5 area(s) as region ID 1 +.P +Create a 1GiB region with 16 areas at the start of vg00/lvol1 +.br +# +.B dmstats create \-\-start 0 \-\-len 1G \-\-areas=16 vg00/lvol1 +.br +vg00-lvol1: Created new region with 16 area(s) as region ID 0 +.P +List the statistics regions registered on vg00/lvol1 +.br +# +.B dmstats list vg00/lvol1 +.br +Name RgID RStart RSize #Areas ASize ProgID +.br +vg00-lvol1 0 0 61.00g 1 61.00g dmstats +.br +vg00-lvol1 1 61.00g 19.20g 1 19.20g dmstats +.br +vg00-lvol1 2 80.20g 2.14g 1 2.14g dmstats +.P +Display five statistics reports for vg00/lvol1 at an interval of one second +.br +.br +# +.B dmstats report \-\-interval 1 \-\-count 5 vg00/lvol1 +.br +# +.B dmstats report +.br +Name RgID ArID AStart ASize RRqM/s WRqM/s R/s W/s RSz/s WSz/s AvRqSz QSize Util% AWait RdAWa WrAWa +.br +vg_hex-lv_home 0 0 0 61.00g 0.00 0.00 0.00 218.00 0 1.04m 4.50k 2.97 81.70 13.62 0.00 13.62 +.br +vg_hex-lv_home 1 0 61.00g 19.20g 0.00 0.00 0.00 5.00 0 548.00k 109.50k 0.14 11.00 27.40 0.00 27.40 +.br +vg_hex-lv_home 2 0 80.20g 2.14g 0.00 0.00 0.00 14.00 0 1.15m 84.00k 0.39 18.70 27.71 0.00 27.71 +.P +Create one region for reach target contained in device vg00/lvol1 +.br +.br +# +.B dmstats create \-\-segments vg00/lvol1 +.br +vg00-lvol1: Created new region with 1 area(s) as region ID 0 +.br +vg00-lvol1: Created new region with 1 area(s) as region ID 1 +.br +vg00-lvol1: Created new region with 1 area(s) as region ID 2 +.P +Create regions mapping each file in the directory images/ and place +them into separate groups, each named after the corresponding file +.br +# +.B dmstats create --filemap images/* +.br +images/vm1.qcow2: Created new group with 87 region(s) as group ID 0. +.br +images/vm1-1.qcow2: Created new group with 8 region(s) as group ID 87. +.br +images/vm2.qcow2: Created new group with 11 region(s) as group ID 95. +.br +images/vm2-1.qcow2: Created new group with 1454 region(s) as group ID 106. +.br +images/vm3.img: Created new group with 2 region(s) as group ID 1560. +.P +Print raw counters for region 4 on device d0 +.br +# +.B dmstats print \-\-regionid 4 d0 +.br +2097152+65536 0 0 0 0 29 0 264 701 0 41 701 0 41 +. +.SH AUTHORS +. +Bryn M. Reeves +. +.SH SEE ALSO +. +.BR dmsetup (8) + +LVM2 resource page: https://www.sourceware.org/lvm2/ +.br +Device-mapper resource page: http://sources.redhat.com/dm/ +.br + +Device-mapper statistics kernel documentation +.br +.I Documentation/device-mapper/statistics.txt diff --git a/man/fsadm.8.in b/man/fsadm.8.in deleted file mode 100644 index 02431c5..0000000 --- a/man/fsadm.8.in +++ /dev/null @@ -1,114 +0,0 @@ -.TH "FSADM" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" -.SH "NAME" -fsadm \(em utility to resize or check filesystem on a device -.SH SYNOPSIS -. -.PD 0 -.ad l -.HP 5 -.B fsadm -.RI [ options ] -.BR check -.IR device -. -.HP -.B fsadm -.RI [ options ] -.BR resize -.IR device -.RI [ new_size ] -.PD -.ad b -. -.SH DESCRIPTION -. -fsadm utility checks or resizes the filesystem on a device. -It tries to use the same API for -.BR ext2 , -.BR ext3 , -.BR ext4 , -.BR ReiserFS -.RB and -.BR XFS -filesystem. -. -.SH OPTIONS -. -.HP -.BR \-e | \-\-ext\-offline -.br -Unmount ext2/ext3/ext4 filesystem before doing resize. -. -.HP -.BR \-f | \-\-force -.br -Bypass some sanity checks. -. -.HP -.BR \-h | \-\-help -.br -Display the help text. -. -.HP -.BR \-n | \-\-dry\-run -.br -Print commands without running them. -. -.HP -.BR \-v | \-\-verbose -.br -Be more verbose. -. -.HP -.BR \-y | \-\-yes -.br -Answer "yes" at any prompts. -. -.HP -.BR \fInew_size [ B | K | M | G | T | P | E ] -.br -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. -. -.SH 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 -.BR fsck (8). -A status code of 1 is used for other failures. -. -.SH EXAMPLES -. -Resize the filesystem on logical volume \fI/dev/vg/test\fP to 1000 megabytes. -If \fI/dev/vg/test\fP contains ext2/ext3/ext4 -filesystem it will be unmounted prior the resize. -All [y/n] questions will be answered 'y'. -.sp -.B fsadm \-e \-y resize /dev/vg/test 1000M -. -.SH ENVIRONMENT VARIABLES -. -.TP -.B "TMPDIR " -The temporary directory name for mount points. Defaults to "\fI/tmp\fP". -.TP -.B DM_DEV_DIR -The device directory name. -Defaults to "\fI/dev\fP" and must be an absolute path. - -.SH SEE ALSO -.nh -.BR lvm (8), -.BR lvresize (8), -.BR lvm.conf (5), -.BR fsck (8), -.BR tune2fs (8), -.BR resize2fs (8), -.BR reiserfstune (8), -.BR resize_reiserfs (8), -.BR xfs_info (8), -.BR xfs_growfs (8), -.BR xfs_check (8) diff --git a/man/fsadm.8_main b/man/fsadm.8_main new file mode 100644 index 0000000..02431c5 --- /dev/null +++ b/man/fsadm.8_main @@ -0,0 +1,114 @@ +.TH "FSADM" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" +.SH "NAME" +fsadm \(em utility to resize or check filesystem on a device +.SH SYNOPSIS +. +.PD 0 +.ad l +.HP 5 +.B fsadm +.RI [ options ] +.BR check +.IR device +. +.HP +.B fsadm +.RI [ options ] +.BR resize +.IR device +.RI [ new_size ] +.PD +.ad b +. +.SH DESCRIPTION +. +fsadm utility checks or resizes the filesystem on a device. +It tries to use the same API for +.BR ext2 , +.BR ext3 , +.BR ext4 , +.BR ReiserFS +.RB and +.BR XFS +filesystem. +. +.SH OPTIONS +. +.HP +.BR \-e | \-\-ext\-offline +.br +Unmount ext2/ext3/ext4 filesystem before doing resize. +. +.HP +.BR \-f | \-\-force +.br +Bypass some sanity checks. +. +.HP +.BR \-h | \-\-help +.br +Display the help text. +. +.HP +.BR \-n | \-\-dry\-run +.br +Print commands without running them. +. +.HP +.BR \-v | \-\-verbose +.br +Be more verbose. +. +.HP +.BR \-y | \-\-yes +.br +Answer "yes" at any prompts. +. +.HP +.BR \fInew_size [ B | K | M | G | T | P | E ] +.br +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. +. +.SH 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 +.BR fsck (8). +A status code of 1 is used for other failures. +. +.SH EXAMPLES +. +Resize the filesystem on logical volume \fI/dev/vg/test\fP to 1000 megabytes. +If \fI/dev/vg/test\fP contains ext2/ext3/ext4 +filesystem it will be unmounted prior the resize. +All [y/n] questions will be answered 'y'. +.sp +.B fsadm \-e \-y resize /dev/vg/test 1000M +. +.SH ENVIRONMENT VARIABLES +. +.TP +.B "TMPDIR " +The temporary directory name for mount points. Defaults to "\fI/tmp\fP". +.TP +.B DM_DEV_DIR +The device directory name. +Defaults to "\fI/dev\fP" and must be an absolute path. + +.SH SEE ALSO +.nh +.BR lvm (8), +.BR lvresize (8), +.BR lvm.conf (5), +.BR fsck (8), +.BR tune2fs (8), +.BR resize2fs (8), +.BR reiserfstune (8), +.BR resize_reiserfs (8), +.BR xfs_info (8), +.BR xfs_growfs (8), +.BR xfs_check (8) diff --git a/man/lvchange.8.des b/man/lvchange.8.des deleted file mode 100644 index 7aa8ce7..0000000 --- a/man/lvchange.8.des +++ /dev/null @@ -1,2 +0,0 @@ -lvchange changes LV attributes in the VG, changes LV activation in the -kernel, and includes other utilities for LV maintenance. diff --git a/man/lvchange.8.end b/man/lvchange.8.end deleted file mode 100644 index 7134e46..0000000 --- a/man/lvchange.8.end +++ /dev/null @@ -1,6 +0,0 @@ -.SH EXAMPLES - -Change LV permission to read-only: -.sp -.B lvchange \-pr vg00/lvol1 - diff --git a/man/lvchange.8_des b/man/lvchange.8_des new file mode 100644 index 0000000..7aa8ce7 --- /dev/null +++ b/man/lvchange.8_des @@ -0,0 +1,2 @@ +lvchange changes LV attributes in the VG, changes LV activation in the +kernel, and includes other utilities for LV maintenance. diff --git a/man/lvchange.8_end b/man/lvchange.8_end new file mode 100644 index 0000000..7134e46 --- /dev/null +++ b/man/lvchange.8_end @@ -0,0 +1,6 @@ +.SH EXAMPLES + +Change LV permission to read-only: +.sp +.B lvchange \-pr vg00/lvol1 + diff --git a/man/lvchange.8_pregen b/man/lvchange.8_pregen new file mode 100644 index 0000000..cba3830 --- /dev/null +++ b/man/lvchange.8_pregen @@ -0,0 +1,1272 @@ +.TH LVCHANGE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvchange \- Change the attributes of logical volume(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvchange\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.P +.ad l + \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP +.ad b +.br +.ad l + \fB--activationmode\fP \fBpartial\fP|\fBdegraded\fP|\fBcomplete\fP +.ad b +.br +.ad l + \fB--addtag\fP \fITag\fP +.ad b +.br +.ad l + \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.ad b +.br +.ad l + \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP +.ad b +.br +.ad l + \fB--cachepolicy\fP \fIString\fP +.ad b +.br +.ad l + \fB--cachesettings\fP \fIString\fP +.ad b +.br +.ad l + \fB--commandprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--config\fP \fIString\fP +.ad b +.br +.ad l + \fB-C\fP|\fB--contiguous\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-d\fP|\fB--debug\fP +.ad b +.br +.ad l + \fB--deltag\fP \fITag\fP +.ad b +.br +.ad l + \fB--detachprofile\fP +.ad b +.br +.ad l + \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP +.ad b +.br +.ad l + \fB--driverloaded\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--errorwhenfull\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-f\fP|\fB--force\fP +.ad b +.br +.ad l + \fB-h\fP|\fB--help\fP +.ad b +.br +.ad l + \fB-K\fP|\fB--ignoreactivationskip\fP +.ad b +.br +.ad l + \fB--ignorelockingfailure\fP +.ad b +.br +.ad l + \fB--ignoremonitoring\fP +.ad b +.br +.ad l + \fB--ignoreskippedcluster\fP +.ad b +.br +.ad l + \fB--longhelp\fP +.ad b +.br +.ad l + \fB-j\fP|\fB--major\fP \fINumber\fP +.ad b +.br +.ad l + \fB--[raid]maxrecoveryrate\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB--metadataprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--minor\fP \fINumber\fP +.ad b +.br +.ad l + \fB--[raid]minrecoveryrate\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB--monitor\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--noudevsync\fP +.ad b +.br +.ad l + \fB-P\fP|\fB--partial\fP +.ad b +.br +.ad l + \fB-p\fP|\fB--permission\fP \fBrw\fP|\fBr\fP +.ad b +.br +.ad l + \fB-M\fP|\fB--persistent\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--poll\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP +.ad b +.br +.ad l + \fB-q\fP|\fB--quiet\fP +.ad b +.br +.ad l + \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP +.ad b +.br +.ad l + \fB--rebuild\fP \fIPV\fP +.ad b +.br +.ad l + \fB--refresh\fP +.ad b +.br +.ad l + \fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.ad b +.br +.ad l + \fB--resync\fP +.ad b +.br +.ad l + \fB-S\fP|\fB--select\fP \fIString\fP +.ad b +.br +.ad l + \fB-k\fP|\fB--setactivationskip\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--[raid]syncaction\fP \fBcheck\fP|\fBrepair\fP +.ad b +.br +.ad l + \fB--sysinit\fP +.ad b +.br +.ad l + \fB-t\fP|\fB--test\fP +.ad b +.br +.ad l + \fB-v\fP|\fB--verbose\fP +.ad b +.br +.ad l + \fB--version\fP +.ad b +.br +.ad l + \fB--[raid]writebehind\fP \fINumber\fP +.ad b +.br +.ad l + \fB--[raid]writemostly\fP \fIPV\fP[\fB:t\fP|\fBn\fP|\fBy\fP] +.ad b +.br +.ad l + \fB-y\fP|\fB--yes\fP +.ad b +.br +.ad l + \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.ad b + +.P + +.SH DESCRIPTION +lvchange changes LV attributes in the VG, changes LV activation in the +kernel, and includes other utilities for LV maintenance. + +.P +.SH USAGE +.br +.P +. +Change a general LV attribute. +.br +For options listed in parentheses, any one is +.br +required, after which the others are optional. +.br +.P +\fBlvchange\fP +.RS 4 +( \fB-C\fP|\fB--contiguous\fP \fBy\fP|\fBn\fP, +.ad b +.br +.ad l + \fB-p\fP|\fB--permission\fP \fBrw\fP|\fBr\fP, +.ad b +.br +.ad l + \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP, +.ad b +.br +.ad l + \fB-k\fP|\fB--setactivationskip\fP \fBy\fP|\fBn\fP, +.ad b +.br +.ad l + \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP, +.ad b +.br +.ad l + \fB-M\fP|\fB--persistent\fP \fBn\fP, +.ad b +.br +.ad l + \fB--addtag\fP \fITag\fP, +.ad b +.br +.ad l + \fB--deltag\fP \fITag\fP, +.ad b +.br +.ad l + \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP, +.ad b +.br +.ad l + \fB--detachprofile\fP, +.ad b +.br +.ad l + \fB--metadataprofile\fP \fIString\fP, +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP, +.ad b +.br +.ad l + \fB--errorwhenfull\fP \fBy\fP|\fBn\fP, +.ad b +.br +.ad l + \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP, +.ad b +.br +.ad l + \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP, +.ad b +.br +.ad l + \fB--cachepolicy\fP \fIString\fP, +.ad b +.br +.ad l + \fB--cachesettings\fP \fIString\fP, +.ad b +.br +.ad l + \fB--[raid]minrecoveryrate\fP \fISize\fP[k|UNIT], +.ad b +.br +.ad l + \fB--[raid]maxrecoveryrate\fP \fISize\fP[k|UNIT], +.ad b +.br +.ad l + \fB--[raid]writebehind\fP \fINumber\fP, +.ad b +.br +.ad l + \fB--[raid]writemostly\fP \fIPV\fP[\fB:t\fP|\fBn\fP|\fBy\fP] ) +.RE +.RS 4 + \fIVG\fP|\fILV\fP|\fITag\fP|\fISelect\fP ... +.RE +.br +.RS 4 +.ad l +[ \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Resyncronize a mirror or raid LV. +.br +.P +\fBlvchange\fP \fB--resync\fP \fIVG\fP|\fILV\fP\fI_mirror_raid\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Resynchronize or check a raid LV. +.br +.P +\fBlvchange\fP \fB--syncaction\fP \fBcheck\fP|\fBrepair\fP \fIVG\fP|\fILV\fP\fI_raid\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Reconstruct data on specific PVs of a raid LV. +.br +.P +\fBlvchange\fP \fB--rebuild\fP \fIPV\fP \fIVG\fP|\fILV\fP\fI_raid\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Activate or deactivate an LV. +.br +.P +\fBlvchange\fP \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP \fIVG\fP|\fILV\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB-K\fP|\fB--ignoreactivationskip\fP ] +.ad b +.br +.ad l +[ \fB--activationmode\fP \fBpartial\fP|\fBdegraded\fP|\fBcomplete\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--sysinit\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Reactivate an LV using the latest metadata. +.br +.P +\fBlvchange\fP \fB--refresh\fP \fIVG\fP|\fILV\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB--poll\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Start or stop monitoring an LV from dmeventd. +.br +.P +\fBlvchange\fP \fB--monitor\fP \fBy\fP|\fBn\fP \fIVG\fP|\fILV\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB--poll\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Start or stop processing an LV conversion. +.br +.P +\fBlvchange\fP \fB--poll\fP \fBy\fP|\fBn\fP \fIVG\fP|\fILV\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB--monitor\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Make the minor device number persistent for an LV. +.br +.P +\fBlvchange\fP \fB-M\fP|\fB--persistent\fP \fBy\fP \fB--minor\fP \fINumber\fP \fILV\fP +.br +.RS 4 +.ad l +[ \fB-j\fP|\fB--major\fP \fINumber\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--ignoremonitoring\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP +.br +Change the active state of LVs. +An active LV can be used through a block device, +allowing data on the LV to be accessed. +\fBy\fP makes LVs active, or available. +\fBn\fP 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. +\fBay\fP specifies autoactivation, in which case an LV is activated +only if it matches an item in lvm.conf activation/auto_activation_volume_list. +If the list is not set, all LVs are considered to match, and if +if the list is set but empty, no LVs match. +Autoactivation should be used during system boot to make it possible +to select which LVs should be automatically activated by the system. +See lvmlockd(8) for more information about activation options \fBey\fP and \fBsy\fP for shared VGs. +See clvmd(8) for more information about activation options \fBey\fP, \fBsy\fP, \fBly\fP and \fBln\fP for clustered VGs. +.ad b + +.HP +.ad l +\fB--activationmode\fP \fBpartial\fP|\fBdegraded\fP|\fBcomplete\fP +.br +Determines if LV activation is allowed when PVs are missing, +e.g. because of a device failure. +\fBcomplete\fP only allows LVs with no missing PVs to be activated, +and is the most restrictive mode. +\fBdegraded\fP allows RAID LVs with missing PVs to be activated. +(This does not include the "mirror" type, see "raid1" instead.) +\fBpartial\fP allows any LV with missing PVs to be activated, and +should only be used for recovery or repair. +For default, see lvm.conf/activation_mode. +See \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--addtag\fP \fITag\fP +.br +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. +.ad b + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP +.br +Specifies when writes to a cache LV should be considered complete. +\fBwriteback\fP considers a write complete as soon as it is +stored in the cache pool. +\fBwritethough\fP 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 \fBpassthrough\fP, 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 \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--cachepolicy\fP \fIString\fP +.br +Specifies the cache policy for a cache LV. +See \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--cachesettings\fP \fIString\fP +.br +Specifies tunable values for a cache LV in "Key = Value" form. +Repeat this option to specify multiple values. +(The default values should usually be adequate.) +The special string value \fBdefault\fP switches +settings back to their default kernel values and removes +them from the list of settings stored in LVM metadata. +See \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-C\fP|\fB--contiguous\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--deltag\fP \fITag\fP +.br +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. +.ad b + +.HP +.ad l +\fB--detachprofile\fP +.br +Detaches a metadata profile from a VG or LV. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP +.br +Specifies how the device-mapper thin pool layer in the kernel should +handle discards. +\fBignore\fP causes the thin pool to ignore discards. +\fBnopassdown\fP causes the thin pool to process discards itself to +allow reuse of unneeded extents in the thin pool. +\fBpassdown\fP causes the thin pool to process discards itself +(like nopassdown) and pass the discards to the underlying device. +See \fBlvmthin\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--errorwhenfull\fP \fBy\fP|\fBn\fP +.br +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 \fBlvmthin\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-K\fP|\fB--ignoreactivationskip\fP +.br +Ignore the "activation skip" LV flag during activation +to allow LVs with the flag set to be activated. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoremonitoring\fP +.br +Do not interact with dmeventd unless --monitor is specified. +Do not use this if dmeventd is already monitoring a device. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-j\fP|\fB--major\fP \fINumber\fP +.br +Sets the major number of an LV block device. +.ad b + +.HP +.ad l +\fB--[raid]maxrecoveryrate\fP \fISize\fP[k|UNIT] +.br +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 \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--metadataprofile\fP \fIString\fP +.br +The metadata profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--minor\fP \fINumber\fP +.br +Sets the minor number of an LV block device. +.ad b + +.HP +.ad l +\fB--[raid]minrecoveryrate\fP \fISize\fP[k|UNIT] +.br +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 \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--monitor\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB-p\fP|\fB--permission\fP \fBrw\fP|\fBr\fP +.br +Set access permission to read only \fBr\fP or read and write \fBrw\fP. +.ad b + +.HP +.ad l +\fB-M\fP|\fB--persistent\fP \fBy\fP|\fBn\fP +.br +When yes, makes the specified minor number persistent. +.ad b + +.HP +.ad l +\fB--poll\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP +.br +Sets read ahead sector count of an LV. +\fBauto\fP is the default which allows the kernel to choose +a suitable value automatically. +\fBnone\fP is equivalent to zero. +.ad b + +.HP +.ad l +\fB--rebuild\fP \fIPV\fP +.br +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 \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--refresh\fP +.br +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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--resync\fP +.br +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 \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB-k\fP|\fB--setactivationskip\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB--[raid]syncaction\fP \fBcheck\fP|\fBrepair\fP +.br +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). +\fBcheck\fP will count but not correct discrepancies. +\fBrepair\fP will correct discrepancies. +See lvs for reporting discrepancies found or repaired. +.ad b + +.HP +.ad l +\fB--sysinit\fP +.br +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. +When used in conjunction with lvmetad enabled and running, +vgchange/lvchange skip autoactivation, and defer to pvscan autoactivation. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB--[raid]writebehind\fP \fINumber\fP +.br +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. +.ad b + +.HP +.ad l +\fB--[raid]writemostly\fP \fIPV\fP[\fB:t\fP|\fBn\fP|\fBy\fP] +.br +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 \fB:n\fP at the end of the PV name, or to toggle the value with +the suffix \fB:t\fP. Repeat this option to change the attribute on +multiple PVs. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b + +.HP +.ad l +\fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.br +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. +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. +LV followed by _ indicates that an LV of the +given type is required. (raid represents raid type) + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fISelect\fP +.br +Select indicates that a required positional parameter can +be omitted if the \fB--select\fP option is used. +No arg appears in this position. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Change LV permission to read-only: +.sp +.B lvchange \-pr vg00/lvol1 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvconvert.8.des b/man/lvconvert.8.des deleted file mode 100644 index 0548c2c..0000000 --- a/man/lvconvert.8.des +++ /dev/null @@ -1,65 +0,0 @@ -lvconvert changes the LV type and includes utilities for LV data -maintenance. The LV type controls data layout and redundancy. -The LV type is also called the segment type or segtype. - -To display the current LV type, run the command: - -.B lvs \-o name,segtype -.I LV - -The -.B linear -type is equivalent to the -.B striped -type when one stripe exists. -In that case, the types can sometimes be used interchangably. - -In most cases, the -.B mirror -type is deprecated and the -.B raid1 -type should be used. They are both implementations of mirroring. - -In some cases, an LV is a single device mapper (dm) layer above physical -devices. In other cases, hidden LVs (dm devices) are layered between the -visible LV and physical devices. LVs in the middle layers are called sub LVs. -A command run on a visible LV sometimes operates on a sub LV rather than -the specified LV. In other cases, a sub LV must be specified directly on -the command line. - -Striped raid types are -.B raid0/raid0_meta -, -.B raid5 -(an alias for raid5_ls), -.B raid6 -(an alias for raid6_zr) and -.B raid10 -(an alias for raid10_near). - -As opposed to mirroring, raid5 and raid6 stripe data and calculate parity -blocks. The parity blocks can be used for data block recovery in case devices -fail. A maximum number of one device in a raid5 LV may fail and two in case -of raid6. Striped raid types typically rotate the parity blocks for performance -reasons thus avoiding contention on a single device. Layouts of raid5 rotating -parity blocks can be one of left-asymmetric (raid5_la), left-symmetric (raid5_ls -with alias raid5), right-asymmetric (raid5_ra), right-symmetric (raid5_rs) and raid5_n, -which doesn't rotate parity blocks. Any \"_n\" layouts allow for conversion between -raid levels (raid5_n -> raid6 or raid5_n -> striped/raid0/raid0_meta). -raid6 layouts are zero-restart (raid6_zr with alias raid6), next-restart (raid6_nr), -next-continue (raid6_nc). Additionally, special raid6 layouts for raid level conversions -between raid5 and raid6 are raid6_ls_6, raid6_rs_6, raid6_la_6 and raid6_ra_6. Those -correspond to their raid5 counterparts (e.g. raid5_rs can be directly converted to raid6_rs_6 -and vice-versa). -raid10 (an alias for raid10_near) is currently limited to one data copy and even number of -sub LVs. This is a mirror group layout thus a single sub LV may fail per mirror group -without data loss. -Striped raid types support converting the layout, their stripesize -and their number of stripes. - -The striped raid types combined with raid1 allow for conversion from linear -> striped/raid0/raid0_meta -and vice-versa by e.g. linear <-> raid1 <-> raid5_n (then adding stripes) <-> striped/raid0/raid0_meta. - -Sub LVs can be displayed with the command -.B lvs -a - diff --git a/man/lvconvert.8.end b/man/lvconvert.8.end deleted file mode 100644 index 5a3d475..0000000 --- a/man/lvconvert.8.end +++ /dev/null @@ -1,116 +0,0 @@ -.SH NOTES - -This previous command syntax would perform two different operations: -.br -\fBlvconvert --thinpool\fP \fILV1\fP \fB--poolmetadata\fP \fILV2\fP -.br -If LV1 was not a thin pool, the command would convert LV1 to -a thin pool, optionally using a specified LV for metadata. -But, if LV1 was already a thin pool, the command would swap -the current metadata LV with LV2 (for repair purposes.) - -In the same way, this previous command syntax would perform two different -operations: -.br -\fBlvconvert --cachepool\fP \fILV1\fP \fB--poolmetadata\fP \fILV2\fP -.br -If LV1 was not a cache pool, the command would convert LV1 to -a cache pool, optionally using a specified LV for metadata. -But, if LV1 was already a cache pool, the command would swap -the current metadata LV with LV2 (for repair purposes.) - -.SH EXAMPLES - -Convert a linear LV to a two-way mirror LV. -.br -.B lvconvert \-\-type mirror \-\-mirrors 1 vg/lvol1 - -Convert a linear LV to a two-way RAID1 LV. -.br -.B lvconvert \-\-type raid1 \-\-mirrors 1 vg/lvol1 - -Convert a mirror LV to use an in\-memory log. -.br -.B lvconvert \-\-mirrorlog core vg/lvol1 - -Convert a mirror LV to use a disk log. -.br -.B lvconvert \-\-mirrorlog disk vg/lvol1 - -Convert a mirror or raid1 LV to a linear LV. -.br -.B lvconvert --type linear vg/lvol1 - -Convert a mirror LV to a raid1 LV with the same number of images. -.br -.B lvconvert \-\-type raid1 vg/lvol1 - -Convert a linear LV to a two-way mirror LV, allocating new extents from specific -PV ranges. -.br -.B lvconvert \-\-mirrors 1 vg/lvol1 /dev/sda:0\-15 /dev/sdb:0\-15 - -Convert a mirror LV to a linear LV, freeing physical extents from a specific PV. -.br -.B lvconvert \-\-type linear vg/lvol1 /dev/sda - -Split one image from a mirror or raid1 LV, making it a new LV. -.br -.B lvconvert \-\-splitmirrors 1 \-\-name lv_split vg/lvol1 - -Split one image from a raid1 LV, and track changes made to the raid1 LV -while the split image remains detached. -.br -.B lvconvert \-\-splitmirrors 1 \-\-trackchanges vg/lvol1 - -Merge an image (that was previously created with \-\-splitmirrors and -\-\-trackchanges) back into the original raid1 LV. -.br -.B lvconvert \-\-mergemirrors vg/lvol1_rimage_1 - -Replace PV /dev/sdb1 with PV /dev/sdf1 in a raid1/4/5/6/10 LV. -.br -.B lvconvert \-\-replace /dev/sdb1 vg/lvol1 /dev/sdf1 - -Replace 3 PVs /dev/sd[b-d]1 with PVs /dev/sd[f-h]1 in a raid1 LV. -.br -.B lvconvert \-\-replace /dev/sdb1 \-\-replace /dev/sdc1 \-\-replace /dev/sdd1 -.RS -.B vg/lvol1 /dev/sd[fgh]1 -.RE - -Replace the maximum of 2 PVs /dev/sd[bc]1 with PVs /dev/sd[gh]1 in a raid6 LV. -.br -.B lvconvert \-\-replace /dev/sdb1 \-\-replace /dev/sdc1 vg/lvol1 /dev/sd[gh]1 - -Convert an LV into a thin LV in the specified thin pool. The existing LV -is used as an external read\-only origin for the new thin LV. -.br -.B lvconvert \-\-type thin \-\-thinpool vg/tpool1 vg/lvol1 - -Convert an LV into a thin LV in the specified thin pool. The existing LV -is used as an external read\-only origin for the new thin LV, and is -renamed "external". -.br -.B lvconvert \-\-type thin \-\-thinpool vg/tpool1 -.RS -.B \-\-originname external vg/lvol1 -.RE - -Convert an LV to a cache pool LV using another specified LV for cache pool -metadata. -.br -.B lvconvert \-\-type cache-pool \-\-poolmetadata vg/poolmeta1 vg/lvol1 - -Convert an LV to a cache LV using the specified cache pool and chunk size. -.br -.B lvconvert \-\-type cache \-\-cachepool vg/cpool1 \-c 128 vg/lvol1 - -Detach and keep the cache pool from a cache LV. -.br -.B lvconvert \-\-splitcache vg/lvol1 - -Detach and remove the cache pool from a cache LV. -.br -.B lvconvert \-\-uncache vg/lvol1 - diff --git a/man/lvconvert.8_des b/man/lvconvert.8_des new file mode 100644 index 0000000..0548c2c --- /dev/null +++ b/man/lvconvert.8_des @@ -0,0 +1,65 @@ +lvconvert changes the LV type and includes utilities for LV data +maintenance. The LV type controls data layout and redundancy. +The LV type is also called the segment type or segtype. + +To display the current LV type, run the command: + +.B lvs \-o name,segtype +.I LV + +The +.B linear +type is equivalent to the +.B striped +type when one stripe exists. +In that case, the types can sometimes be used interchangably. + +In most cases, the +.B mirror +type is deprecated and the +.B raid1 +type should be used. They are both implementations of mirroring. + +In some cases, an LV is a single device mapper (dm) layer above physical +devices. In other cases, hidden LVs (dm devices) are layered between the +visible LV and physical devices. LVs in the middle layers are called sub LVs. +A command run on a visible LV sometimes operates on a sub LV rather than +the specified LV. In other cases, a sub LV must be specified directly on +the command line. + +Striped raid types are +.B raid0/raid0_meta +, +.B raid5 +(an alias for raid5_ls), +.B raid6 +(an alias for raid6_zr) and +.B raid10 +(an alias for raid10_near). + +As opposed to mirroring, raid5 and raid6 stripe data and calculate parity +blocks. The parity blocks can be used for data block recovery in case devices +fail. A maximum number of one device in a raid5 LV may fail and two in case +of raid6. Striped raid types typically rotate the parity blocks for performance +reasons thus avoiding contention on a single device. Layouts of raid5 rotating +parity blocks can be one of left-asymmetric (raid5_la), left-symmetric (raid5_ls +with alias raid5), right-asymmetric (raid5_ra), right-symmetric (raid5_rs) and raid5_n, +which doesn't rotate parity blocks. Any \"_n\" layouts allow for conversion between +raid levels (raid5_n -> raid6 or raid5_n -> striped/raid0/raid0_meta). +raid6 layouts are zero-restart (raid6_zr with alias raid6), next-restart (raid6_nr), +next-continue (raid6_nc). Additionally, special raid6 layouts for raid level conversions +between raid5 and raid6 are raid6_ls_6, raid6_rs_6, raid6_la_6 and raid6_ra_6. Those +correspond to their raid5 counterparts (e.g. raid5_rs can be directly converted to raid6_rs_6 +and vice-versa). +raid10 (an alias for raid10_near) is currently limited to one data copy and even number of +sub LVs. This is a mirror group layout thus a single sub LV may fail per mirror group +without data loss. +Striped raid types support converting the layout, their stripesize +and their number of stripes. + +The striped raid types combined with raid1 allow for conversion from linear -> striped/raid0/raid0_meta +and vice-versa by e.g. linear <-> raid1 <-> raid5_n (then adding stripes) <-> striped/raid0/raid0_meta. + +Sub LVs can be displayed with the command +.B lvs -a + diff --git a/man/lvconvert.8_end b/man/lvconvert.8_end new file mode 100644 index 0000000..5a3d475 --- /dev/null +++ b/man/lvconvert.8_end @@ -0,0 +1,116 @@ +.SH NOTES + +This previous command syntax would perform two different operations: +.br +\fBlvconvert --thinpool\fP \fILV1\fP \fB--poolmetadata\fP \fILV2\fP +.br +If LV1 was not a thin pool, the command would convert LV1 to +a thin pool, optionally using a specified LV for metadata. +But, if LV1 was already a thin pool, the command would swap +the current metadata LV with LV2 (for repair purposes.) + +In the same way, this previous command syntax would perform two different +operations: +.br +\fBlvconvert --cachepool\fP \fILV1\fP \fB--poolmetadata\fP \fILV2\fP +.br +If LV1 was not a cache pool, the command would convert LV1 to +a cache pool, optionally using a specified LV for metadata. +But, if LV1 was already a cache pool, the command would swap +the current metadata LV with LV2 (for repair purposes.) + +.SH EXAMPLES + +Convert a linear LV to a two-way mirror LV. +.br +.B lvconvert \-\-type mirror \-\-mirrors 1 vg/lvol1 + +Convert a linear LV to a two-way RAID1 LV. +.br +.B lvconvert \-\-type raid1 \-\-mirrors 1 vg/lvol1 + +Convert a mirror LV to use an in\-memory log. +.br +.B lvconvert \-\-mirrorlog core vg/lvol1 + +Convert a mirror LV to use a disk log. +.br +.B lvconvert \-\-mirrorlog disk vg/lvol1 + +Convert a mirror or raid1 LV to a linear LV. +.br +.B lvconvert --type linear vg/lvol1 + +Convert a mirror LV to a raid1 LV with the same number of images. +.br +.B lvconvert \-\-type raid1 vg/lvol1 + +Convert a linear LV to a two-way mirror LV, allocating new extents from specific +PV ranges. +.br +.B lvconvert \-\-mirrors 1 vg/lvol1 /dev/sda:0\-15 /dev/sdb:0\-15 + +Convert a mirror LV to a linear LV, freeing physical extents from a specific PV. +.br +.B lvconvert \-\-type linear vg/lvol1 /dev/sda + +Split one image from a mirror or raid1 LV, making it a new LV. +.br +.B lvconvert \-\-splitmirrors 1 \-\-name lv_split vg/lvol1 + +Split one image from a raid1 LV, and track changes made to the raid1 LV +while the split image remains detached. +.br +.B lvconvert \-\-splitmirrors 1 \-\-trackchanges vg/lvol1 + +Merge an image (that was previously created with \-\-splitmirrors and +\-\-trackchanges) back into the original raid1 LV. +.br +.B lvconvert \-\-mergemirrors vg/lvol1_rimage_1 + +Replace PV /dev/sdb1 with PV /dev/sdf1 in a raid1/4/5/6/10 LV. +.br +.B lvconvert \-\-replace /dev/sdb1 vg/lvol1 /dev/sdf1 + +Replace 3 PVs /dev/sd[b-d]1 with PVs /dev/sd[f-h]1 in a raid1 LV. +.br +.B lvconvert \-\-replace /dev/sdb1 \-\-replace /dev/sdc1 \-\-replace /dev/sdd1 +.RS +.B vg/lvol1 /dev/sd[fgh]1 +.RE + +Replace the maximum of 2 PVs /dev/sd[bc]1 with PVs /dev/sd[gh]1 in a raid6 LV. +.br +.B lvconvert \-\-replace /dev/sdb1 \-\-replace /dev/sdc1 vg/lvol1 /dev/sd[gh]1 + +Convert an LV into a thin LV in the specified thin pool. The existing LV +is used as an external read\-only origin for the new thin LV. +.br +.B lvconvert \-\-type thin \-\-thinpool vg/tpool1 vg/lvol1 + +Convert an LV into a thin LV in the specified thin pool. The existing LV +is used as an external read\-only origin for the new thin LV, and is +renamed "external". +.br +.B lvconvert \-\-type thin \-\-thinpool vg/tpool1 +.RS +.B \-\-originname external vg/lvol1 +.RE + +Convert an LV to a cache pool LV using another specified LV for cache pool +metadata. +.br +.B lvconvert \-\-type cache-pool \-\-poolmetadata vg/poolmeta1 vg/lvol1 + +Convert an LV to a cache LV using the specified cache pool and chunk size. +.br +.B lvconvert \-\-type cache \-\-cachepool vg/cpool1 \-c 128 vg/lvol1 + +Detach and keep the cache pool from a cache LV. +.br +.B lvconvert \-\-splitcache vg/lvol1 + +Detach and remove the cache pool from a cache LV. +.br +.B lvconvert \-\-uncache vg/lvol1 + diff --git a/man/lvconvert.8_pregen b/man/lvconvert.8_pregen new file mode 100644 index 0000000..bc8d53f --- /dev/null +++ b/man/lvconvert.8_pregen @@ -0,0 +1,2059 @@ +.TH LVCONVERT 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvconvert \- Change logical volume layout +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvconvert\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.P +.ad l + \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.ad b +.br +.ad l + \fB-b\fP|\fB--background\fP +.ad b +.br +.ad l + \fB-H\fP|\fB--cache\fP +.ad b +.br +.ad l + \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP +.ad b +.br +.ad l + \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP +.ad b +.br +.ad l + \fB--cachepolicy\fP \fIString\fP +.ad b +.br +.ad l + \fB--cachepool\fP \fILV\fP +.ad b +.br +.ad l + \fB--cachesettings\fP \fIString\fP +.ad b +.br +.ad l + \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB--commandprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--config\fP \fIString\fP +.ad b +.br +.ad l + \fB-d\fP|\fB--debug\fP +.ad b +.br +.ad l + \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP +.ad b +.br +.ad l + \fB--driverloaded\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-f\fP|\fB--force\fP +.ad b +.br +.ad l + \fB-h\fP|\fB--help\fP +.ad b +.br +.ad l + \fB-i\fP|\fB--interval\fP \fINumber\fP +.ad b +.br +.ad l + \fB--longhelp\fP +.ad b +.br +.ad l + \fB--merge\fP +.ad b +.br +.ad l + \fB--mergemirrors\fP +.ad b +.br +.ad l + \fB--mergesnapshot\fP +.ad b +.br +.ad l + \fB--mergethin\fP +.ad b +.br +.ad l + \fB--metadataprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP +.ad b +.br +.ad l + \fB-m\fP|\fB--mirrors\fP [\fB+\fP|\fB-\fP]\fINumber\fP +.ad b +.br +.ad l + \fB-n\fP|\fB--name\fP \fIString\fP +.ad b +.br +.ad l + \fB--noudevsync\fP +.ad b +.br +.ad l + \fB--originname\fP \fILV\fP +.ad b +.br +.ad l + \fB--poolmetadata\fP \fILV\fP +.ad b +.br +.ad l + \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP +.ad b +.br +.ad l + \fB-q\fP|\fB--quiet\fP +.ad b +.br +.ad l + \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP +.ad b +.br +.ad l + \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB--repair\fP +.ad b +.br +.ad l + \fB--replace\fP \fIPV\fP +.ad b +.br +.ad l + \fB-s\fP|\fB--snapshot\fP +.ad b +.br +.ad l + \fB--splitcache\fP +.ad b +.br +.ad l + \fB--splitmirrors\fP \fINumber\fP +.ad b +.br +.ad l + \fB--splitsnapshot\fP +.ad b +.br +.ad l + \fB--startpoll\fP +.ad b +.br +.ad l + \fB--stripes\fP \fINumber\fP +.ad b +.br +.ad l + \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB--swapmetadata\fP +.ad b +.br +.ad l + \fB-t\fP|\fB--test\fP +.ad b +.br +.ad l + \fB-T\fP|\fB--thin\fP +.ad b +.br +.ad l + \fB--thinpool\fP \fILV\fP +.ad b +.br +.ad l + \fB--trackchanges\fP +.ad b +.br +.ad l + \fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP +.ad b +.br +.ad l + \fB--uncache\fP +.ad b +.br +.ad l + \fB--usepolicies\fP +.ad b +.br +.ad l + \fB-v\fP|\fB--verbose\fP +.ad b +.br +.ad l + \fB--version\fP +.ad b +.br +.ad l + \fB-y\fP|\fB--yes\fP +.ad b +.br +.ad l + \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.ad b + +.P + +.SH DESCRIPTION +lvconvert changes the LV type and includes utilities for LV data +maintenance. The LV type controls data layout and redundancy. +The LV type is also called the segment type or segtype. + +To display the current LV type, run the command: + +.B lvs \-o name,segtype +.I LV + +The +.B linear +type is equivalent to the +.B striped +type when one stripe exists. +In that case, the types can sometimes be used interchangably. + +In most cases, the +.B mirror +type is deprecated and the +.B raid1 +type should be used. They are both implementations of mirroring. + +In some cases, an LV is a single device mapper (dm) layer above physical +devices. In other cases, hidden LVs (dm devices) are layered between the +visible LV and physical devices. LVs in the middle layers are called sub LVs. +A command run on a visible LV sometimes operates on a sub LV rather than +the specified LV. In other cases, a sub LV must be specified directly on +the command line. + +Striped raid types are +.B raid0/raid0_meta +, +.B raid5 +(an alias for raid5_ls), +.B raid6 +(an alias for raid6_zr) and +.B raid10 +(an alias for raid10_near). + +As opposed to mirroring, raid5 and raid6 stripe data and calculate parity +blocks. The parity blocks can be used for data block recovery in case devices +fail. A maximum number of one device in a raid5 LV may fail and two in case +of raid6. Striped raid types typically rotate the parity blocks for performance +reasons thus avoiding contention on a single device. Layouts of raid5 rotating +parity blocks can be one of left-asymmetric (raid5_la), left-symmetric (raid5_ls +with alias raid5), right-asymmetric (raid5_ra), right-symmetric (raid5_rs) and raid5_n, +which doesn't rotate parity blocks. Any \"_n\" layouts allow for conversion between +raid levels (raid5_n -> raid6 or raid5_n -> striped/raid0/raid0_meta). +raid6 layouts are zero-restart (raid6_zr with alias raid6), next-restart (raid6_nr), +next-continue (raid6_nc). Additionally, special raid6 layouts for raid level conversions +between raid5 and raid6 are raid6_ls_6, raid6_rs_6, raid6_la_6 and raid6_ra_6. Those +correspond to their raid5 counterparts (e.g. raid5_rs can be directly converted to raid6_rs_6 +and vice-versa). +raid10 (an alias for raid10_near) is currently limited to one data copy and even number of +sub LVs. This is a mirror group layout thus a single sub LV may fail per mirror group +without data loss. +Striped raid types support converting the layout, their stripesize +and their number of stripes. + +The striped raid types combined with raid1 allow for conversion from linear -> striped/raid0/raid0_meta +and vice-versa by e.g. linear <-> raid1 <-> raid5_n (then adding stripes) <-> striped/raid0/raid0_meta. + +Sub LVs can be displayed with the command +.B lvs -a + + +.P +.SH USAGE +.br +.P +. +Convert LV to linear. +.br +.P +\fBlvconvert\fP \fB--type\fP \fBlinear\fP \fILV\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Convert LV to striped. +.br +.P +\fBlvconvert\fP \fB--type\fP \fBstriped\fP \fILV\fP +.br +.RS 4 +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--stripes\fP \fINumber\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Convert LV to raid or change raid layout +.br +(a specific raid level must be used, e.g. raid1). +.br +.P +\fBlvconvert\fP \fB--type\fP \fBraid\fP \fILV\fP +.br +.RS 4 +.ad l +[ \fB-m\fP|\fB--mirrors\fP [\fB+\fP|\fB-\fP]\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--stripes\fP \fINumber\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Convert LV to raid1 or mirror, or change number of mirror images. +.br +.P +\fBlvconvert\fP \fB-m\fP|\fB--mirrors\fP [\fB+\fP|\fB-\fP]\fINumber\fP \fILV\fP +.br +.RS 4 +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Convert raid LV to change number of stripe images. +.br +.P +\fBlvconvert\fP \fB--stripes\fP \fINumber\fP \fILV\fP\fI_raid\fP +.br +.RS 4 +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Convert raid LV to change the stripe size. +.br +.P +\fBlvconvert\fP \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] \fILV\fP\fI_raid\fP +.br +.RS 4 +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Split images from a raid1 or mirror LV and use them to create a new LV. +.br +.P +\fBlvconvert\fP \fB--splitmirrors\fP \fINumber\fP \fB-n\fP|\fB--name\fP \fILV\fP\fI_new\fP \fILV\fP\fI_cache_mirror_raid1\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Split images from a raid1 LV and track changes to origin. +.br +.P +\fBlvconvert\fP \fB--splitmirrors\fP \fINumber\fP \fB--trackchanges\fP \fILV\fP\fI_cache_raid1\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Merge LV images that were split from a raid1 LV. +.br +.P +\fBlvconvert\fP \fB--mergemirrors\fP \fIVG\fP|\fILV\fP\fI_linear_raid\fP|\fITag\fP ... +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Convert LV to a thin LV, using the original LV as an external origin. +.br +.P +\fBlvconvert\fP \fB--type\fP \fBthin\fP \fB--thinpool\fP \fILV\fP \fILV\fP\fI_linear_striped_cache_raid\fP +.br +.RS 4 +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--originname\fP \fILV\fP\fI_new\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadata\fP \fILV\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Convert LV to type cache. +.br +.P +\fBlvconvert\fP \fB--type\fP \fBcache\fP \fB--cachepool\fP \fILV\fP \fILV\fP\fI_linear_striped_thinpool_raid\fP +.br +.RS 4 +.ad l +[ \fB-H\fP|\fB--cache\fP ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadata\fP \fILV\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Convert LV to type thin-pool. +.br +.P +\fBlvconvert\fP \fB--type\fP \fBthin-pool\fP \fILV\fP\fI_linear_striped_cache_raid\fP +.br +.RS 4 +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadata\fP \fILV\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Convert LV to type cache-pool. +.br +.P +\fBlvconvert\fP \fB--type\fP \fBcache-pool\fP \fILV\fP\fI_linear_striped_raid\fP +.br +.RS 4 +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadata\fP \fILV\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Separate and keep the cache pool from a cache LV. +.br +.P +\fBlvconvert\fP \fB--splitcache\fP \fILV\fP\fI_thinpool_cache_cachepool\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Merge thin LV into its origin LV. +.br +.P +\fBlvconvert\fP \fB--mergethin\fP \fILV\fP\fI_thin\fP ... +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Merge COW snapshot LV into its origin. +.br +.P +\fBlvconvert\fP \fB--mergesnapshot\fP \fILV\fP\fI_snapshot\fP ... +.br +.RS 4 +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Replace failed PVs in a raid or mirror LV. +.br +Repair a thin pool. +.br +.P +\fBlvconvert\fP \fB--repair\fP \fILV\fP\fI_thinpool_mirror_raid\fP +.br +.RS 4 +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--usepolicies\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Replace specific PV(s) in a raid LV with another PV. +.br +.P +\fBlvconvert\fP \fB--replace\fP \fIPV\fP \fILV\fP\fI_raid\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Poll LV to continue conversion. +.br +.P +\fBlvconvert\fP \fB--startpoll\fP \fILV\fP\fI_mirror_raid\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Common options for command: +. +.RS 4 +.ad l +[ \fB-b\fP|\fB--background\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB-b\fP|\fB--background\fP +.br +If the operation requires polling, this option causes the command to +return before the operation is complete, and polling is done in the +background. +.ad b + +.HP +.ad l +\fB-H\fP|\fB--cache\fP +.br +Specifies the command is handling a cache LV or cache pool. +See --type cache and --type cache-pool. +See \fBlvmcache\fP(7) for more information about LVM caching. +.ad b + +.HP +.ad l +\fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP +.br +Specifies the cache metadata format used by cache target. +.ad b + +.HP +.ad l +\fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP +.br +Specifies when writes to a cache LV should be considered complete. +\fBwriteback\fP considers a write complete as soon as it is +stored in the cache pool. +\fBwritethough\fP 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 \fBpassthrough\fP, 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 \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--cachepolicy\fP \fIString\fP +.br +Specifies the cache policy for a cache LV. +See \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--cachepool\fP \fILV\fP +.br +The name of a cache pool LV. +.ad b + +.HP +.ad l +\fB--cachesettings\fP \fIString\fP +.br +Specifies tunable values for a cache LV in "Key = Value" form. +Repeat this option to specify multiple values. +(The default values should usually be adequate.) +The special string value \fBdefault\fP switches +settings back to their default kernel values and removes +them from the list of settings stored in LVM metadata. +See \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] +.br +The size of chunks in a snapshot, cache pool or thin pool. +For snapshots, the value must be a power of 2 between 4KiB and 512KiB +and the default value is 4. +For a cache pool the value must be between 32KiB and 1GiB +and the default value is 64. +For a thin pool the value must be between 64KiB and 1GiB +and the default value starts with 64 and scales up to fit the +pool metadata size within 128MiB, if the pool metadata size is not specified. +The value must be a multiple of 64KiB. +See \fBlvmthin\fP(7) and \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP +.br +Specifies how the device-mapper thin pool layer in the kernel should +handle discards. +\fBignore\fP causes the thin pool to ignore discards. +\fBnopassdown\fP causes the thin pool to process discards itself to +allow reuse of unneeded extents in the thin pool. +\fBpassdown\fP causes the thin pool to process discards itself +(like nopassdown) and pass the discards to the underlying device. +See \fBlvmthin\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-i\fP|\fB--interval\fP \fINumber\fP +.br +Report progress at regular intervals. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--merge\fP +.br +An alias for --mergethin, --mergemirrors, or --mergesnapshot, +depending on the type of LV. +.ad b + +.HP +.ad l +\fB--mergemirrors\fP +.br +Merge LV images that were split from a raid1 LV. +See --splitmirrors with --trackchanges. +.ad b + +.HP +.ad l +\fB--mergesnapshot\fP +.br +Merge COW snapshot LV into its origin. +When merging a snapshot, if both the origin and snapshot LVs are not open, +the merge will start immediately. Otherwise, the merge will start the +first time either the origin or snapshot LV are activated and both are +closed. Merging a snapshot into an origin that cannot be closed, for +example a root filesystem, is deferred until the next time the origin +volume is activated. When merging starts, the resulting LV will have the +origin's name, minor number and UUID. While the merge is in progress, +reads or writes to the origin appear as being directed to the snapshot +being merged. When the merge finishes, the merged snapshot is removed. +Multiple snapshots may be specified on the command line or a @tag may be +used to specify multiple snapshots be merged to their respective origin. +.ad b + +.HP +.ad l +\fB--mergethin\fP +.br +Merge thin LV into its origin LV. +The origin thin LV takes the content of the thin snapshot, +and the thin snapshot LV is removed. +See \fBlvmthin\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--metadataprofile\fP \fIString\fP +.br +The metadata profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP +.br +Specifies the type of mirror log for LVs with the "mirror" type +(does not apply to the "raid1" type.) +\fBdisk\fP is a persistent log and requires a small amount of +storage space, usually on a separate device from the data being mirrored. +\fBcore\fP is not persistent; the log is kept only in memory. +In this case, the mirror must be synchronized (by copying LV data from +the first device to others) each time the LV is activated, e.g. after reboot. +\fBmirrored\fP is a persistent log that is itself mirrored. +.ad b + +.HP +.ad l +\fB-m\fP|\fB--mirrors\fP [\fB+\fP|\fB-\fP]\fINumber\fP +.br +Specifies the number of mirror images in addition to the original LV +image, e.g. --mirrors 1 means there are two images of the data, the +original and one mirror image. +Optional positional PV args on the command line can specify the devices +the images should be placed on. +There are two mirroring implementations: "raid1" and "mirror". +These are the names of the corresponding LV types, or "segment types". +Use the --type option to specify which to use (raid1 is default, +and mirror is legacy) +Use lvm.conf global/mirror_segtype_default and +global/raid10_segtype_default to configure the default types. +The plus prefix \fB+\fP can be used, in which case +the number is added to the current number of images, +or the minus prefix \fB-\fP can be used, in which case +the number is subtracted from the current number of images. +See \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-n\fP|\fB--name\fP \fIString\fP +.br +Specifies the name of a new LV. +When unspecified, a default name of "lvol#" is +generated, where # is a number generated by LVM. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB--originname\fP \fILV\fP +.br +Specifies the name to use for the external origin LV when converting an LV +to a thin LV. The LV being converted becomes a read-only external origin +with this name. +.ad b + +.HP +.ad l +\fB--poolmetadata\fP \fILV\fP +.br +The name of a an LV to use for storing pool metadata. +.ad b + +.HP +.ad l +\fB--poolmetadatasize\fP \fISize\fP[m|UNIT] +.br +Specifies the size of the new pool metadata LV. +.ad b + +.HP +.ad l +\fB--poolmetadataspare\fP \fBy\fP|\fBn\fP +.br +Enable or disable the automatic creation and management of a +spare pool metadata LV in the VG. A spare metadata LV is reserved +space that can be used when repairing a pool. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP +.br +Sets read ahead sector count of an LV. +\fBauto\fP is the default which allows the kernel to choose +a suitable value automatically. +\fBnone\fP is equivalent to zero. +.ad b + +.HP +.ad l +\fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] +.br +Size of each raid or mirror synchronization region. +lvm.conf activation/raid_region_size can be used to +configure a default. +.ad b + +.HP +.ad l +\fB--repair\fP +.br +Replace failed PVs in a raid or mirror LV, or run a repair +utility on a thin pool. See \fBlvmraid\fP(7) and \fBlvmthin\fP(7) +for more information. +.ad b + +.HP +.ad l +\fB--replace\fP \fIPV\fP +.br +Replace a specific PV in a raid LV with another PV. +The new PV to use can be optionally specified after the LV. +Multiple PVs can be replaced by repeating this option. +See \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-s\fP|\fB--snapshot\fP +.br +Combine a former COW snapshot LV with a former origin LV to reverse +a previous --splitsnapshot command. +.ad b + +.HP +.ad l +\fB--splitcache\fP +.br +Separates a cache pool from a cache LV, and keeps the unused cache pool LV. +Before the separation, the cache is flushed. Also see --uncache. +.ad b + +.HP +.ad l +\fB--splitmirrors\fP \fINumber\fP +.br +Splits the specified number of images from a raid1 or mirror LV +and uses them to create a new LV. If --trackchanges is also specified, +changes to the raid1 LV are tracked while the split LV remains detached. +.ad b + +.HP +.ad l +\fB--splitsnapshot\fP +.br +Separates a COW snapshot from its origin LV. The LV that is split off +contains the chunks that differ from the origin LV along with metadata +describing them. This LV can be wiped and then destroyed with lvremove. +.ad b + +.HP +.ad l +\fB--startpoll\fP +.br +Start polling an LV to continue processing a conversion. +.ad b + +.HP +.ad l +\fB--stripes\fP \fINumber\fP +.br +Specifies the number of stripes in a striped LV. This is the number of +PVs (devices) that a striped LV is spread across. Data that +appears sequential in the LV is spread across multiple devices in units of +the stripe size (see --stripesize). This does not apply to +existing allocated space, only newly allocated space can be striped. +.ad b + +.HP +.ad l +\fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] +.br +The amount of data that is written to one device before +moving to the next in a striped LV. +.ad b + +.HP +.ad l +\fB--swapmetadata\fP +.br +Extracts the metadata LV from a pool and replaces it with another specified LV. +The extracted LV is preserved and given the name of the LV that replaced it. +Use for repair only. When the metadata LV is swapped out of the pool, it can +be activated directly and used with thin provisioning tools: +\fBcache_dump\fP(8), \fBcache_repair\fP(8), \fBcache_restore\fP(8), +\fBthin_dump\fP(8), \fBthin_repair\fP(8), \fBthin_restore\fP(8). +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-T\fP|\fB--thin\fP +.br +Specifies the command is handling a thin LV or thin pool. +See --type thin, --type thin-pool, and --virtualsize. +See \fBlvmthin\fP(7) for more information about LVM thin provisioning. +.ad b + +.HP +.ad l +\fB--thinpool\fP \fILV\fP +.br +The name of a thin pool LV. +.ad b + +.HP +.ad l +\fB--trackchanges\fP +.br +Can be used with --splitmirrors on a raid1 LV. This causes +changes to the original raid1 LV to be tracked while the split images +remain detached. This allows the read-only detached image(s) to be +merged efficiently back into the raid1 LV later. Only the regions with +changed data are resynchronized during merge. (This option only applies +when using the raid1 LV type.) +.ad b + +.HP +.ad l +\fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP +.br +The LV type, also known as "segment type" or "segtype". +See usage descriptions for the specific ways to use these types. +For more information about redundancy and performance (\fBraid\fP, \fBmirror\fP, \fBstriped\fP, \fBlinear\fP) see \fBlvmraid\fP(7). +For thin provisioning (\fBthin\fP, \fBthin-pool\fP) see \fBlvmthin\fP(7). +For performance caching (\fBcache\fP, \fBcache-pool\fP) see \fBlvmcache\fP(7). +For copy-on-write snapshots (\fBsnapshot\fP) see usage definitions. +Several commands omit an explicit type option because the type +is inferred from other options or shortcuts +(e.g. --stripes, --mirrors, --snapshot, --virtualsize, --thin, --cache). +Use inferred types with care because it can lead to unexpected results. +.ad b + +.HP +.ad l +\fB--uncache\fP +.br +Separates a cache pool from a cache LV, and deletes the unused cache pool LV. +Before the separation, the cache is flushed. Also see --splitcache. +.ad b + +.HP +.ad l +\fB--usepolicies\fP +.br +Perform an operation according to the policy configured in lvm.conf +or a profile. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b + +.HP +.ad l +\fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.br +For snapshots, this controls zeroing of the first 4KiB of data in the +snapshot. If the LV is read-only, the snapshot will not be zeroed. +For thin pools, this controls zeroing of provisioned blocks. +Provisioning of large zeroed chunks negatively impacts performance. +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. +LV followed by _ indicates that an LV of the +given type is required. (raid represents raid type) + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH ADVANCED USAGE +Alternate command forms, advanced command usage, and listing of all valid syntax for completeness. +.P +Convert LV to type mirror (also see type raid1), +.br +(also see lvconvert --mirrors). +.br +.P +\fBlvconvert\fP \fB--type\fP \fBmirror\fP \fILV\fP +.br +.RS 4 +.ad l +[ \fB-m\fP|\fB--mirrors\fP [\fB+\fP|\fB-\fP]\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Change the region size of an LV. +.br +.P +\fBlvconvert\fP \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] \fILV\fP\fI_raid\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Change the type of mirror log used by a mirror LV. +.br +.P +\fBlvconvert\fP \fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP \fILV\fP\fI_mirror\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Convert LV to a thin LV, using the original LV as an external origin +.br +(infers --type thin). +.br +.P +\fBlvconvert\fP \fB-T\fP|\fB--thin\fP \fB--thinpool\fP \fILV\fP \fILV\fP\fI_linear_striped_cache_raid\fP +.br +.RS 4 +.ad l +[ \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--originname\fP \fILV\fP\fI_new\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadata\fP \fILV\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Convert LV to type cache (infers --type cache). +.br +.P +\fBlvconvert\fP \fB-H\fP|\fB--cache\fP \fB--cachepool\fP \fILV\fP \fILV\fP\fI_linear_striped_thinpool_raid\fP +.br +.RS 4 +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBcache\fP ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadata\fP \fILV\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Separate and delete the cache pool from a cache LV. +.br +.P +\fBlvconvert\fP \fB--uncache\fP \fILV\fP\fI_thinpool_cache\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Swap metadata LV in a thin pool or cache pool (for repair only). +.br +.P +\fBlvconvert\fP \fB--swapmetadata\fP \fB--poolmetadata\fP \fILV\fP \fILV\fP\fI_thinpool_cachepool\fP +.br +.RS 4 +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Merge LV that was split from a mirror (variant, use --mergemirrors). +.br +Merge thin LV into its origin LV (variant, use --mergethin). +.br +Merge COW snapshot LV into its origin (variant, use --mergesnapshot). +.br +.P +\fBlvconvert\fP \fB--merge\fP \fIVG\fP|\fILV\fP\fI_linear_striped_snapshot_thin_raid\fP|\fITag\fP ... +.br +.RS 4 +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Separate a COW snapshot from its origin LV. +.br +.P +\fBlvconvert\fP \fB--splitsnapshot\fP \fILV\fP\fI_snapshot\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Combine a former COW snapshot (second arg) with a former +.br +origin LV (first arg) to reverse a splitsnapshot command. +.br +.P +\fBlvconvert\fP \fB--type\fP \fBsnapshot\fP \fILV\fP \fILV\fP\fI_linear\fP +.br +.RS 4 +.ad l +[ \fB-s\fP|\fB--snapshot\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Combine a former COW snapshot (second arg) with a former +.br +origin LV (first arg) to reverse a splitsnapshot command. +.br +.P +\fBlvconvert\fP \fB-s\fP|\fB--snapshot\fP \fILV\fP \fILV\fP\fI_linear\fP +.br +.RS 4 +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--type\fP \fBsnapshot\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Poll LV to continue conversion (also see --startpoll). +.br +.P +\fBlvconvert\fP \fILV\fP\fI_mirror_raid\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +.SH NOTES + +This previous command syntax would perform two different operations: +.br +\fBlvconvert --thinpool\fP \fILV1\fP \fB--poolmetadata\fP \fILV2\fP +.br +If LV1 was not a thin pool, the command would convert LV1 to +a thin pool, optionally using a specified LV for metadata. +But, if LV1 was already a thin pool, the command would swap +the current metadata LV with LV2 (for repair purposes.) + +In the same way, this previous command syntax would perform two different +operations: +.br +\fBlvconvert --cachepool\fP \fILV1\fP \fB--poolmetadata\fP \fILV2\fP +.br +If LV1 was not a cache pool, the command would convert LV1 to +a cache pool, optionally using a specified LV for metadata. +But, if LV1 was already a cache pool, the command would swap +the current metadata LV with LV2 (for repair purposes.) + +.SH EXAMPLES + +Convert a linear LV to a two-way mirror LV. +.br +.B lvconvert \-\-type mirror \-\-mirrors 1 vg/lvol1 + +Convert a linear LV to a two-way RAID1 LV. +.br +.B lvconvert \-\-type raid1 \-\-mirrors 1 vg/lvol1 + +Convert a mirror LV to use an in\-memory log. +.br +.B lvconvert \-\-mirrorlog core vg/lvol1 + +Convert a mirror LV to use a disk log. +.br +.B lvconvert \-\-mirrorlog disk vg/lvol1 + +Convert a mirror or raid1 LV to a linear LV. +.br +.B lvconvert --type linear vg/lvol1 + +Convert a mirror LV to a raid1 LV with the same number of images. +.br +.B lvconvert \-\-type raid1 vg/lvol1 + +Convert a linear LV to a two-way mirror LV, allocating new extents from specific +PV ranges. +.br +.B lvconvert \-\-mirrors 1 vg/lvol1 /dev/sda:0\-15 /dev/sdb:0\-15 + +Convert a mirror LV to a linear LV, freeing physical extents from a specific PV. +.br +.B lvconvert \-\-type linear vg/lvol1 /dev/sda + +Split one image from a mirror or raid1 LV, making it a new LV. +.br +.B lvconvert \-\-splitmirrors 1 \-\-name lv_split vg/lvol1 + +Split one image from a raid1 LV, and track changes made to the raid1 LV +while the split image remains detached. +.br +.B lvconvert \-\-splitmirrors 1 \-\-trackchanges vg/lvol1 + +Merge an image (that was previously created with \-\-splitmirrors and +\-\-trackchanges) back into the original raid1 LV. +.br +.B lvconvert \-\-mergemirrors vg/lvol1_rimage_1 + +Replace PV /dev/sdb1 with PV /dev/sdf1 in a raid1/4/5/6/10 LV. +.br +.B lvconvert \-\-replace /dev/sdb1 vg/lvol1 /dev/sdf1 + +Replace 3 PVs /dev/sd[b-d]1 with PVs /dev/sd[f-h]1 in a raid1 LV. +.br +.B lvconvert \-\-replace /dev/sdb1 \-\-replace /dev/sdc1 \-\-replace /dev/sdd1 +.RS +.B vg/lvol1 /dev/sd[fgh]1 +.RE + +Replace the maximum of 2 PVs /dev/sd[bc]1 with PVs /dev/sd[gh]1 in a raid6 LV. +.br +.B lvconvert \-\-replace /dev/sdb1 \-\-replace /dev/sdc1 vg/lvol1 /dev/sd[gh]1 + +Convert an LV into a thin LV in the specified thin pool. The existing LV +is used as an external read\-only origin for the new thin LV. +.br +.B lvconvert \-\-type thin \-\-thinpool vg/tpool1 vg/lvol1 + +Convert an LV into a thin LV in the specified thin pool. The existing LV +is used as an external read\-only origin for the new thin LV, and is +renamed "external". +.br +.B lvconvert \-\-type thin \-\-thinpool vg/tpool1 +.RS +.B \-\-originname external vg/lvol1 +.RE + +Convert an LV to a cache pool LV using another specified LV for cache pool +metadata. +.br +.B lvconvert \-\-type cache-pool \-\-poolmetadata vg/poolmeta1 vg/lvol1 + +Convert an LV to a cache LV using the specified cache pool and chunk size. +.br +.B lvconvert \-\-type cache \-\-cachepool vg/cpool1 \-c 128 vg/lvol1 + +Detach and keep the cache pool from a cache LV. +.br +.B lvconvert \-\-splitcache vg/lvol1 + +Detach and remove the cache pool from a cache LV. +.br +.B lvconvert \-\-uncache vg/lvol1 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvcreate.8.des b/man/lvcreate.8.des deleted file mode 100644 index acc07b3..0000000 --- a/man/lvcreate.8.des +++ /dev/null @@ -1,39 +0,0 @@ -lvcreate creates a new LV in a VG. For standard LVs, this requires -allocating logical extents from the VG's free physical extents. If there -is not enough free space, then the VG can be extended (see -\fBvgextend\fP(8)) with other PVs, or existing LVs can be reduced or -removed (see \fBlvremove\fP, \fBlvreduce\fP.) - -To control which PVs a new LV will use, specify one or more PVs as -position args at the end of the command line. lvcreate will allocate -physical extents only from the specified PVs. - -lvcreate can also create snapshots of existing LVs, e.g. for backup -purposes. The data in a new snapshot LV represents the content of the -original LV from the time the snapshot was created. - -RAID LVs can be created by specifying an LV type when creating the LV (see -\fBlvmraid\fP(7)). Different RAID levels require different numbers of -unique PVs be available in the VG for allocation. - -Thin pools (for thin provisioning) and cache pools (for caching) are -represented by special LVs with types thin-pool and cache-pool (see -\fBlvmthin\fP(7) and \fBlvmcache\fP(7)). The pool LVs are not usable as -standard block devices, but the LV names act references to the pools. - -Thin LVs are thinly provisioned from a thin pool, and are created with a -virtual size rather than a physical size. A cache LV is the combination of -a standard LV with a cache pool, used to cache active portions of the LV -to improve performance. - -.SS Usage notes - -In the usage section below, \fB--size\fP \fISize\fP can be replaced -with \fB--extents\fP \fINumber\fP. See both descriptions -the options section. - -In the usage section below, \fB--name\fP is omitted from the required -options, even though it is typically used. When the name is not -specified, a new LV name is generated with the "lvol" prefix and a unique -numeric suffix. Also see the description in the options section. - diff --git a/man/lvcreate.8.end b/man/lvcreate.8.end deleted file mode 100644 index 74ae599..0000000 --- a/man/lvcreate.8.end +++ /dev/null @@ -1,98 +0,0 @@ -.SH EXAMPLES - -Create a striped LV with 3 stripes, a stripe size of 8KiB and a size of 100MiB. -The LV name is chosen by lvcreate. -.br -.B lvcreate \-i 3 \-I 8 \-L 100m vg00 - -Create a raid1 LV with two images, and a useable size of 500 MiB. This -operation requires two devices, one for each mirror image. RAID metadata -(superblock and bitmap) is also included on the two devices. -.br -.B lvcreate \-\-type raid1 \-m1 \-L 500m \-n mylv vg00 - -Create a mirror LV with two images, and a useable size of 500 MiB. -This operation requires three devices: two for mirror images and -one for a disk log. -.br -.B lvcreate \-\-type mirror \-m1 \-L 500m \-n mylv vg00 - -Create a mirror LV with 2 images, and a useable size of 500 MiB. -This operation requires 2 devices because the log is in memory. -.br -.B lvcreate \-\-type mirror \-m1 \-\-mirrorlog core \-L 500m \-n mylv vg00 - -Create a copy\-on\-write snapshot of an LV: -.br -.B lvcreate \-\-snapshot \-\-size 100m \-\-name mysnap vg00/mylv - -Create a copy\-on\-write snapshot with a size sufficient -for overwriting 20% of the size of the original LV. -.br -.B lvcreate \-s \-l 20%ORIGIN \-n mysnap vg00/mylv - -Create a sparse LV with 1TiB of virtual space, and actual space just under -100MiB. -.br -.B lvcreate \-\-snapshot \-\-virtualsize 1t \-\-size 100m \-\-name mylv vg00 - -Create a linear LV with a usable size of 64MiB on specific physical extents. -.br -.B lvcreate \-L 64m \-n mylv vg00 /dev/sda:0\-7 /dev/sdb:0\-7 - -Create a RAID5 LV with a usable size of 5GiB, 3 stripes, a stripe size of -64KiB, using a total of 4 devices (including one for parity). -.br -.B lvcreate \-\-type raid5 \-L 5G \-i 3 \-I 64 \-n mylv vg00 - -Create a RAID5 LV using all of the free space in the VG and spanning all the -PVs in the VG (note that the command will fail if there are more than 8 PVs in -the VG, in which case \fB\-i 7\fP must be used to get to the current maximum of -8 devices including parity for RaidLVs). -.br -.B lvcreate \-\-config allocation/raid_stripe_all_devices=1 -.RS -.B \-\-type raid5 \-l 100%FREE \-n mylv vg00 -.RE - -Create RAID10 LV with a usable size of 5GiB, using 2 stripes, each on -a two-image mirror. (Note that the \fB-i\fP and \fB-m\fP arguments behave -differently: -\fB-i\fP specifies the total number of stripes, -but \fB-m\fP specifies the number of images in addition -to the first image). -.br -.B lvcreate \-\-type raid10 \-L 5G \-i 2 \-m 1 \-n mylv vg00 - -Create a 1TiB thin LV, first creating a new thin pool for it, where -the thin pool has 100MiB of space, uses 2 stripes, has a 64KiB stripe -size, and 256KiB chunk size. -.br -.B lvcreate \-\-type thin \-\-name mylv \-\-thinpool mypool -.RS -.B \-V 1t \-L 100m \-i 2 \-I 64 \-c 256 vg00 -.RE - -Create a thin snapshot of a thin LV (the size option must not be -used, otherwise a copy-on-write snapshot would be created). -.br -.B lvcreate \-\-snapshot \-\-name mysnap vg00/thinvol - -Create a thin snapshot of the read-only inactive LV named "origin" -which becomes an external origin for the thin snapshot LV. -.br -.B lvcreate \-\-snapshot \-\-name mysnap \-\-thinpool mypool vg00/origin - -Create a cache pool from a fast physical device. The cache pool can -then be used to cache an LV. -.br -.B lvcreate \-\-type cache-pool \-L 1G \-n my_cpool vg00 /dev/fast1 - -Create a cache LV, first creating a new origin LV on a slow physical device, -then combining the new origin LV with an existing cache pool. -.br -.B lvcreate \-\-type cache \-\-cachepool my_cpool -.RS -.B \-L 100G \-n mylv vg00 /dev/slow1 -.RE - diff --git a/man/lvcreate.8_des b/man/lvcreate.8_des new file mode 100644 index 0000000..acc07b3 --- /dev/null +++ b/man/lvcreate.8_des @@ -0,0 +1,39 @@ +lvcreate creates a new LV in a VG. For standard LVs, this requires +allocating logical extents from the VG's free physical extents. If there +is not enough free space, then the VG can be extended (see +\fBvgextend\fP(8)) with other PVs, or existing LVs can be reduced or +removed (see \fBlvremove\fP, \fBlvreduce\fP.) + +To control which PVs a new LV will use, specify one or more PVs as +position args at the end of the command line. lvcreate will allocate +physical extents only from the specified PVs. + +lvcreate can also create snapshots of existing LVs, e.g. for backup +purposes. The data in a new snapshot LV represents the content of the +original LV from the time the snapshot was created. + +RAID LVs can be created by specifying an LV type when creating the LV (see +\fBlvmraid\fP(7)). Different RAID levels require different numbers of +unique PVs be available in the VG for allocation. + +Thin pools (for thin provisioning) and cache pools (for caching) are +represented by special LVs with types thin-pool and cache-pool (see +\fBlvmthin\fP(7) and \fBlvmcache\fP(7)). The pool LVs are not usable as +standard block devices, but the LV names act references to the pools. + +Thin LVs are thinly provisioned from a thin pool, and are created with a +virtual size rather than a physical size. A cache LV is the combination of +a standard LV with a cache pool, used to cache active portions of the LV +to improve performance. + +.SS Usage notes + +In the usage section below, \fB--size\fP \fISize\fP can be replaced +with \fB--extents\fP \fINumber\fP. See both descriptions +the options section. + +In the usage section below, \fB--name\fP is omitted from the required +options, even though it is typically used. When the name is not +specified, a new LV name is generated with the "lvol" prefix and a unique +numeric suffix. Also see the description in the options section. + diff --git a/man/lvcreate.8_end b/man/lvcreate.8_end new file mode 100644 index 0000000..74ae599 --- /dev/null +++ b/man/lvcreate.8_end @@ -0,0 +1,98 @@ +.SH EXAMPLES + +Create a striped LV with 3 stripes, a stripe size of 8KiB and a size of 100MiB. +The LV name is chosen by lvcreate. +.br +.B lvcreate \-i 3 \-I 8 \-L 100m vg00 + +Create a raid1 LV with two images, and a useable size of 500 MiB. This +operation requires two devices, one for each mirror image. RAID metadata +(superblock and bitmap) is also included on the two devices. +.br +.B lvcreate \-\-type raid1 \-m1 \-L 500m \-n mylv vg00 + +Create a mirror LV with two images, and a useable size of 500 MiB. +This operation requires three devices: two for mirror images and +one for a disk log. +.br +.B lvcreate \-\-type mirror \-m1 \-L 500m \-n mylv vg00 + +Create a mirror LV with 2 images, and a useable size of 500 MiB. +This operation requires 2 devices because the log is in memory. +.br +.B lvcreate \-\-type mirror \-m1 \-\-mirrorlog core \-L 500m \-n mylv vg00 + +Create a copy\-on\-write snapshot of an LV: +.br +.B lvcreate \-\-snapshot \-\-size 100m \-\-name mysnap vg00/mylv + +Create a copy\-on\-write snapshot with a size sufficient +for overwriting 20% of the size of the original LV. +.br +.B lvcreate \-s \-l 20%ORIGIN \-n mysnap vg00/mylv + +Create a sparse LV with 1TiB of virtual space, and actual space just under +100MiB. +.br +.B lvcreate \-\-snapshot \-\-virtualsize 1t \-\-size 100m \-\-name mylv vg00 + +Create a linear LV with a usable size of 64MiB on specific physical extents. +.br +.B lvcreate \-L 64m \-n mylv vg00 /dev/sda:0\-7 /dev/sdb:0\-7 + +Create a RAID5 LV with a usable size of 5GiB, 3 stripes, a stripe size of +64KiB, using a total of 4 devices (including one for parity). +.br +.B lvcreate \-\-type raid5 \-L 5G \-i 3 \-I 64 \-n mylv vg00 + +Create a RAID5 LV using all of the free space in the VG and spanning all the +PVs in the VG (note that the command will fail if there are more than 8 PVs in +the VG, in which case \fB\-i 7\fP must be used to get to the current maximum of +8 devices including parity for RaidLVs). +.br +.B lvcreate \-\-config allocation/raid_stripe_all_devices=1 +.RS +.B \-\-type raid5 \-l 100%FREE \-n mylv vg00 +.RE + +Create RAID10 LV with a usable size of 5GiB, using 2 stripes, each on +a two-image mirror. (Note that the \fB-i\fP and \fB-m\fP arguments behave +differently: +\fB-i\fP specifies the total number of stripes, +but \fB-m\fP specifies the number of images in addition +to the first image). +.br +.B lvcreate \-\-type raid10 \-L 5G \-i 2 \-m 1 \-n mylv vg00 + +Create a 1TiB thin LV, first creating a new thin pool for it, where +the thin pool has 100MiB of space, uses 2 stripes, has a 64KiB stripe +size, and 256KiB chunk size. +.br +.B lvcreate \-\-type thin \-\-name mylv \-\-thinpool mypool +.RS +.B \-V 1t \-L 100m \-i 2 \-I 64 \-c 256 vg00 +.RE + +Create a thin snapshot of a thin LV (the size option must not be +used, otherwise a copy-on-write snapshot would be created). +.br +.B lvcreate \-\-snapshot \-\-name mysnap vg00/thinvol + +Create a thin snapshot of the read-only inactive LV named "origin" +which becomes an external origin for the thin snapshot LV. +.br +.B lvcreate \-\-snapshot \-\-name mysnap \-\-thinpool mypool vg00/origin + +Create a cache pool from a fast physical device. The cache pool can +then be used to cache an LV. +.br +.B lvcreate \-\-type cache-pool \-L 1G \-n my_cpool vg00 /dev/fast1 + +Create a cache LV, first creating a new origin LV on a slow physical device, +then combining the new origin LV with an existing cache pool. +.br +.B lvcreate \-\-type cache \-\-cachepool my_cpool +.RS +.B \-L 100G \-n mylv vg00 /dev/slow1 +.RE + diff --git a/man/lvcreate.8_pregen b/man/lvcreate.8_pregen new file mode 100644 index 0000000..49d9072 --- /dev/null +++ b/man/lvcreate.8_pregen @@ -0,0 +1,2865 @@ +.TH LVCREATE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvcreate \- Create a logical volume +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvcreate\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.P +.ad l + \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP +.ad b +.br +.ad l + \fB--addtag\fP \fITag\fP +.ad b +.br +.ad l + \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.ad b +.br +.ad l + \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-H\fP|\fB--cache\fP +.ad b +.br +.ad l + \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP +.ad b +.br +.ad l + \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP +.ad b +.br +.ad l + \fB--cachepolicy\fP \fIString\fP +.ad b +.br +.ad l + \fB--cachepool\fP \fILV\fP +.ad b +.br +.ad l + \fB--cachesettings\fP \fIString\fP +.ad b +.br +.ad l + \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB--commandprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--config\fP \fIString\fP +.ad b +.br +.ad l + \fB-C\fP|\fB--contiguous\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-d\fP|\fB--debug\fP +.ad b +.br +.ad l + \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP +.ad b +.br +.ad l + \fB--driverloaded\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--errorwhenfull\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] +.ad b +.br +.ad l + \fB-h\fP|\fB--help\fP +.ad b +.br +.ad l + \fB-K\fP|\fB--ignoreactivationskip\fP +.ad b +.br +.ad l + \fB--ignoremonitoring\fP +.ad b +.br +.ad l + \fB--longhelp\fP +.ad b +.br +.ad l + \fB-j\fP|\fB--major\fP \fINumber\fP +.ad b +.br +.ad l + \fB--[raid]maxrecoveryrate\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB--metadataprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--minor\fP \fINumber\fP +.ad b +.br +.ad l + \fB--[raid]minrecoveryrate\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP +.ad b +.br +.ad l + \fB-m\fP|\fB--mirrors\fP \fINumber\fP +.ad b +.br +.ad l + \fB--monitor\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-n\fP|\fB--name\fP \fIString\fP +.ad b +.br +.ad l + \fB--nosync\fP +.ad b +.br +.ad l + \fB--noudevsync\fP +.ad b +.br +.ad l + \fB-p\fP|\fB--permission\fP \fBrw\fP|\fBr\fP +.ad b +.br +.ad l + \fB-M\fP|\fB--persistent\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP +.ad b +.br +.ad l + \fB-q\fP|\fB--quiet\fP +.ad b +.br +.ad l + \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP +.ad b +.br +.ad l + \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.ad b +.br +.ad l + \fB-k\fP|\fB--setactivationskip\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB-s\fP|\fB--snapshot\fP +.ad b +.br +.ad l + \fB-i\fP|\fB--stripes\fP \fINumber\fP +.ad b +.br +.ad l + \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB-t\fP|\fB--test\fP +.ad b +.br +.ad l + \fB-T\fP|\fB--thin\fP +.ad b +.br +.ad l + \fB--thinpool\fP \fILV\fP +.ad b +.br +.ad l + \fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP +.ad b +.br +.ad l + \fB-v\fP|\fB--verbose\fP +.ad b +.br +.ad l + \fB--version\fP +.ad b +.br +.ad l + \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB-W\fP|\fB--wipesignatures\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-y\fP|\fB--yes\fP +.ad b +.br +.ad l + \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.ad b + +.P + +.SH DESCRIPTION +lvcreate creates a new LV in a VG. For standard LVs, this requires +allocating logical extents from the VG's free physical extents. If there +is not enough free space, then the VG can be extended (see +\fBvgextend\fP(8)) with other PVs, or existing LVs can be reduced or +removed (see \fBlvremove\fP, \fBlvreduce\fP.) + +To control which PVs a new LV will use, specify one or more PVs as +position args at the end of the command line. lvcreate will allocate +physical extents only from the specified PVs. + +lvcreate can also create snapshots of existing LVs, e.g. for backup +purposes. The data in a new snapshot LV represents the content of the +original LV from the time the snapshot was created. + +RAID LVs can be created by specifying an LV type when creating the LV (see +\fBlvmraid\fP(7)). Different RAID levels require different numbers of +unique PVs be available in the VG for allocation. + +Thin pools (for thin provisioning) and cache pools (for caching) are +represented by special LVs with types thin-pool and cache-pool (see +\fBlvmthin\fP(7) and \fBlvmcache\fP(7)). The pool LVs are not usable as +standard block devices, but the LV names act references to the pools. + +Thin LVs are thinly provisioned from a thin pool, and are created with a +virtual size rather than a physical size. A cache LV is the combination of +a standard LV with a cache pool, used to cache active portions of the LV +to improve performance. + +.SS Usage notes + +In the usage section below, \fB--size\fP \fISize\fP can be replaced +with \fB--extents\fP \fINumber\fP. See both descriptions +the options section. + +In the usage section below, \fB--name\fP is omitted from the required +options, even though it is typically used. When the name is not +specified, a new LV name is generated with the "lvol" prefix and a unique +numeric suffix. Also see the description in the options section. + + +.P +.SH USAGE +.br +.P +. +Create a linear LV. +.br +.P +\fBlvcreate\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBlinear\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a striped LV (infers --type striped). +.br +.P +\fBlvcreate\fP \fB-i\fP|\fB--stripes\fP \fINumber\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBstriped\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a raid1 or mirror LV (infers --type raid1|mirror). +.br +.P +\fBlvcreate\fP \fB-m\fP|\fB--mirrors\fP \fINumber\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-m\fP|\fB--mirrors\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBraid1\fP ] +.ad b +.br +.ad l +[ \fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP ] +.ad b +.br +.ad l +[ \fB--[raid]minrecoveryrate\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--[raid]maxrecoveryrate\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a raid LV (a specific raid level must be used, e.g. raid1). +.br +.P +\fBlvcreate\fP \fB--type\fP \fBraid\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-m\fP|\fB--mirrors\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--[raid]minrecoveryrate\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--[raid]maxrecoveryrate\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a COW snapshot LV of an origin LV. +.br +.P +\fBlvcreate\fP \fB-s\fP|\fB--snapshot\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fILV\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBsnapshot\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a thin pool. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBthin-pool\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--thinpool\fP \fILV\fP\fI_new\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a cache pool. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBcache-pool\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-H\fP|\fB--cache\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a thin LV in a thin pool (infers --type thin). +.br +.P +\fBlvcreate\fP \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] \fB--thinpool\fP \fILV\fP\fI_thinpool\fP \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV that is a snapshot of an existing thin LV +.br +(infers --type thin). +.br +.P +\fBlvcreate\fP \fB-s\fP|\fB--snapshot\fP \fILV\fP\fI_thin\fP +.br +.RS 4 +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV that is a snapshot of an external origin LV. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBthin\fP \fB--thinpool\fP \fILV\fP\fI_thinpool\fP \fILV\fP +.br +.RS 4 +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV, first creating a thin pool for it, +.br +where the new thin pool is named by the --thinpool arg. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBthin\fP \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] +.RS 5 + \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fB--thinpool\fP \fILV\fP\fI_new\fP +.RE +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a cache LV, first creating a new origin LV, +.br +then combining it with the existing cache pool named +.br +by the --cachepool arg. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBcache\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] +.RS 5 + \fB--cachepool\fP \fILV\fP\fI_cachepool\fP \fIVG\fP +.RE +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-H\fP|\fB--cache\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Common options for command: +. +.RS 4 +.ad l +[ \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP ] +.ad b +.br +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-C\fP|\fB--contiguous\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-K\fP|\fB--ignoreactivationskip\fP ] +.ad b +.br +.ad l +[ \fB-j\fP|\fB--major\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-n\fP|\fB--name\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-p\fP|\fB--permission\fP \fBrw\fP|\fBr\fP ] +.ad b +.br +.ad l +[ \fB-M\fP|\fB--persistent\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP ] +.ad b +.br +.ad l +[ \fB-k\fP|\fB--setactivationskip\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-W\fP|\fB--wipesignatures\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--addtag\fP \fITag\fP ] +.ad b +.br +.ad l +[ \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP ] +.ad b +.br +.ad l +[ \fB--ignoremonitoring\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--minor\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--monitor\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--nosync\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP +.br +Controls the active state of the new LV. +\fBy\fP makes the LV active, or available. +New LVs are made active by default. +\fBn\fP makes the LV inactive, or unavailable, only when possible. +In some cases, creating an LV requires it to be active. +For example, COW snapshots of an active origin LV can only +be created in the active state (this does not apply to thin snapshots.) +The --zero option normally requires the LV to be active. +If autoactivation \fBay\fP is used, the LV is only activated +if it matches an item in lvm.conf activation/auto_activation_volume_list. +\fBay\fP implies --zero n and --wipesignatures n. +See lvmlockd(8) for more information about activation options for shared VGs. +See clvmd(8) for more information about activation options for clustered VGs. +.ad b + +.HP +.ad l +\fB--addtag\fP \fITag\fP +.br +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. +.ad b + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB-H\fP|\fB--cache\fP +.br +Specifies the command is handling a cache LV or cache pool. +See --type cache and --type cache-pool. +See \fBlvmcache\fP(7) for more information about LVM caching. +.ad b + +.HP +.ad l +\fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP +.br +Specifies the cache metadata format used by cache target. +.ad b + +.HP +.ad l +\fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP +.br +Specifies when writes to a cache LV should be considered complete. +\fBwriteback\fP considers a write complete as soon as it is +stored in the cache pool. +\fBwritethough\fP 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 \fBpassthrough\fP, 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 \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--cachepolicy\fP \fIString\fP +.br +Specifies the cache policy for a cache LV. +See \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--cachepool\fP \fILV\fP +.br +The name of a cache pool LV. +.ad b + +.HP +.ad l +\fB--cachesettings\fP \fIString\fP +.br +Specifies tunable values for a cache LV in "Key = Value" form. +Repeat this option to specify multiple values. +(The default values should usually be adequate.) +The special string value \fBdefault\fP switches +settings back to their default kernel values and removes +them from the list of settings stored in LVM metadata. +See \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] +.br +The size of chunks in a snapshot, cache pool or thin pool. +For snapshots, the value must be a power of 2 between 4KiB and 512KiB +and the default value is 4. +For a cache pool the value must be between 32KiB and 1GiB +and the default value is 64. +For a thin pool the value must be between 64KiB and 1GiB +and the default value starts with 64 and scales up to fit the +pool metadata size within 128MiB, if the pool metadata size is not specified. +The value must be a multiple of 64KiB. +See \fBlvmthin\fP(7) and \fBlvmcache\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-C\fP|\fB--contiguous\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP +.br +Specifies how the device-mapper thin pool layer in the kernel should +handle discards. +\fBignore\fP causes the thin pool to ignore discards. +\fBnopassdown\fP causes the thin pool to process discards itself to +allow reuse of unneeded extents in the thin pool. +\fBpassdown\fP causes the thin pool to process discards itself +(like nopassdown) and pass the discards to the underlying device. +See \fBlvmthin\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--errorwhenfull\fP \fBy\fP|\fBn\fP +.br +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 \fBlvmthin\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] +.br +Specifies the size of the new LV in logical extents. +The --size and --extents options are alternate methods of specifying size. +The total number of physical extents used will be +greater when redundant data is needed for RAID levels. +An alternate syntax allows the size to be determined indirectly +as a percentage of the size of a related VG, LV, or set of PVs. The +suffix \fB%VG\fP denotes the total size of the VG, the suffix \fB%FREE\fP +the remaining free space in the VG, and the suffix \fB%PVS\fP the free +space in the specified PVs. For a snapshot, the size +can be expressed as a percentage of the total size of the origin LV +with the suffix \fB%ORIGIN\fP (\fB100%ORIGIN\fP provides space for +the whole origin). +When expressed as a percentage, the size defines an upper limit for the +number of logical extents in the new LV. The precise number of logical +extents in the new LV is not determined until the command has completed. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-K\fP|\fB--ignoreactivationskip\fP +.br +Ignore the "activation skip" LV flag during activation +to allow LVs with the flag set to be activated. +.ad b + +.HP +.ad l +\fB--ignoremonitoring\fP +.br +Do not interact with dmeventd unless --monitor is specified. +Do not use this if dmeventd is already monitoring a device. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-j\fP|\fB--major\fP \fINumber\fP +.br +Sets the major number of an LV block device. +.ad b + +.HP +.ad l +\fB--[raid]maxrecoveryrate\fP \fISize\fP[k|UNIT] +.br +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 \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--metadataprofile\fP \fIString\fP +.br +The metadata profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--minor\fP \fINumber\fP +.br +Sets the minor number of an LV block device. +.ad b + +.HP +.ad l +\fB--[raid]minrecoveryrate\fP \fISize\fP[k|UNIT] +.br +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 \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP +.br +Specifies the type of mirror log for LVs with the "mirror" type +(does not apply to the "raid1" type.) +\fBdisk\fP is a persistent log and requires a small amount of +storage space, usually on a separate device from the data being mirrored. +\fBcore\fP is not persistent; the log is kept only in memory. +In this case, the mirror must be synchronized (by copying LV data from +the first device to others) each time the LV is activated, e.g. after reboot. +\fBmirrored\fP is a persistent log that is itself mirrored. +.ad b + +.HP +.ad l +\fB-m\fP|\fB--mirrors\fP \fINumber\fP +.br +Specifies the number of mirror images in addition to the original LV +image, e.g. --mirrors 1 means there are two images of the data, the +original and one mirror image. +Optional positional PV args on the command line can specify the devices +the images should be placed on. +There are two mirroring implementations: "raid1" and "mirror". +These are the names of the corresponding LV types, or "segment types". +Use the --type option to specify which to use (raid1 is default, +and mirror is legacy) +Use lvm.conf global/mirror_segtype_default and +global/raid10_segtype_default to configure the default types. +See the --nosync option for avoiding initial image synchronization. +See \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--monitor\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB-n\fP|\fB--name\fP \fIString\fP +.br +Specifies the name of a new LV. +When unspecified, a default name of "lvol#" is +generated, where # is a number generated by LVM. +.ad b + +.HP +.ad l +\fB--nosync\fP +.br +Causes the creation of mirror, raid1, raid4, raid5 and raid10 to skip the +initial synchronization. In case of mirror, raid1 and raid10, any data +written afterwards will be mirrored, but the original contents will not be +copied. In case of raid4 and raid5, no parity blocks will be written, +though any data written afterwards will cause parity blocks to be stored. +This is useful for skipping a potentially long and resource intensive initial +sync of an empty mirror/raid1/raid4/raid5 and raid10 LV. +This option is not valid for raid6, because raid6 relies on proper parity +(P and Q Syndromes) being created during initial synchronization in order +to reconstruct proper user date in case of device failures. +raid0 and raid0_meta do not provide any data copies or parity support +and thus do not support initial synchronization. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB-p\fP|\fB--permission\fP \fBrw\fP|\fBr\fP +.br +Set access permission to read only \fBr\fP or read and write \fBrw\fP. +.ad b + +.HP +.ad l +\fB-M\fP|\fB--persistent\fP \fBy\fP|\fBn\fP +.br +When yes, makes the specified minor number persistent. +.ad b + +.HP +.ad l +\fB--poolmetadatasize\fP \fISize\fP[m|UNIT] +.br +Specifies the size of the new pool metadata LV. +.ad b + +.HP +.ad l +\fB--poolmetadataspare\fP \fBy\fP|\fBn\fP +.br +Enable or disable the automatic creation and management of a +spare pool metadata LV in the VG. A spare metadata LV is reserved +space that can be used when repairing a pool. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-r\fP|\fB--readahead\fP \fBauto\fP|\fBnone\fP|\fINumber\fP +.br +Sets read ahead sector count of an LV. +\fBauto\fP is the default which allows the kernel to choose +a suitable value automatically. +\fBnone\fP is equivalent to zero. +.ad b + +.HP +.ad l +\fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] +.br +Size of each raid or mirror synchronization region. +lvm.conf activation/raid_region_size can be used to +configure a default. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-k\fP|\fB--setactivationskip\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] +.br +Specifies the size of the new LV. +The --size and --extents options are alternate methods of specifying size. +The total number of physical extents used will be +greater when redundant data is needed for RAID levels. +.ad b + +.HP +.ad l +\fB-s\fP|\fB--snapshot\fP +.br +Create a snapshot. Snapshots provide a "frozen image" of an origin LV. +The snapshot LV can be used, e.g. for backups, while the origin LV +continues to be used. +This option can create a COW (copy on write) snapshot, +or a thin snapshot (in a thin pool.) +Thin snapshots are created when the origin is a thin LV and +the size option is NOT specified. Thin snapshots share the same blocks +in the thin pool, and do not allocate new space from the VG. +Thin snapshots are created with the "activation skip" flag, +see --setactivationskip. +A thin snapshot of a non-thin "external origin" LV is created +when a thin pool is specified. Unprovisioned blocks in the thin snapshot +LV are read from the external origin LV. The external origin LV must +be read-only. +See \fBlvmthin\fP(7) for more information about LVM thin provisioning. +COW snapshots are created when a size is specified. The size is allocated +from space in the VG, and is the amount of space that can be used +for saving COW blocks as writes occur to the origin or snapshot. +The size chosen should depend upon the amount of writes that are expected; +often 20% of the origin LV is enough. If COW space runs low, it can +be extended with lvextend (shrinking is also allowed with lvreduce.) +A small amount of the COW snapshot LV size is used to track COW block +locations, so the full size is not available for COW data blocks. +Use lvs to check how much space is used, and see --monitor to +to automatically extend the size to avoid running out of space. +.ad b + +.HP +.ad l +\fB-i\fP|\fB--stripes\fP \fINumber\fP +.br +Specifies the number of stripes in a striped LV. This is the number of +PVs (devices) that a striped LV is spread across. Data that +appears sequential in the LV is spread across multiple devices in units of +the stripe size (see --stripesize). This does not change existing +allocated space, but only applies to space being allocated by the command. +When creating a RAID 4/5/6 LV, this number does not include the extra +devices that are required for parity. The largest number depends on +the RAID type (raid0: 64, raid10: 32, raid4/5: 63, raid6: 62), and +when unspecified, the default depends on the RAID type +(raid0: 2, raid10: 4, raid4/5: 3, raid6: 5.) +To stripe a new raid LV across all PVs by default, +see lvm.conf allocation/raid_stripe_all_devices. +.ad b + +.HP +.ad l +\fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] +.br +The amount of data that is written to one device before +moving to the next in a striped LV. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-T\fP|\fB--thin\fP +.br +Specifies the command is handling a thin LV or thin pool. +See --type thin, --type thin-pool, and --virtualsize. +See \fBlvmthin\fP(7) for more information about LVM thin provisioning. +.ad b + +.HP +.ad l +\fB--thinpool\fP \fILV\fP +.br +The name of a thin pool LV. +.ad b + +.HP +.ad l +\fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP +.br +The LV type, also known as "segment type" or "segtype". +See usage descriptions for the specific ways to use these types. +For more information about redundancy and performance (\fBraid\fP, \fBmirror\fP, \fBstriped\fP, \fBlinear\fP) see \fBlvmraid\fP(7). +For thin provisioning (\fBthin\fP, \fBthin-pool\fP) see \fBlvmthin\fP(7). +For performance caching (\fBcache\fP, \fBcache-pool\fP) see \fBlvmcache\fP(7). +For copy-on-write snapshots (\fBsnapshot\fP) see usage definitions. +Several commands omit an explicit type option because the type +is inferred from other options or shortcuts +(e.g. --stripes, --mirrors, --snapshot, --virtualsize, --thin, --cache). +Use inferred types with care because it can lead to unexpected results. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] +.br +The virtual size of a new thin LV. +See \fBlvmthin\fP(7) for more information about LVM thin provisioning. +Using virtual size (-V) and actual size (-L) together creates +a sparse LV. +lvm.conf global/sparse_segtype_default determines the +default segment type used to create a sparse LV. +Anything written to a sparse LV will be returned when reading from it. +Reading from other areas of the LV will return blocks of zeros. +When using a snapshot to create a sparse LV, a hidden virtual device +is created using the zero target, and the LV has the suffix _vorigin. +Snapshots are less efficient than thin provisioning when creating +large sparse LVs (GiB). +.ad b + +.HP +.ad l +\fB-W\fP|\fB--wipesignatures\fP \fBy\fP|\fBn\fP +.br +Controls detection and subsequent wiping of signatures on new LVs. +There is a prompt for each signature detected to confirm its wiping +(unless --yes is used to override confirmations.) +When not specified, signatures are wiped whenever zeroing is done +(see --zero). This behaviour can be configured with +lvm.conf allocation/wipe_signatures_when_zeroing_new_lvs. +If blkid wiping is used (lvm.conf allocation/use_blkid_wiping) +and LVM is compiled with blkid wiping support, then the blkid(8) +library is used to detect the signatures (use blkid -k to list the +signatures that are recognized). +Otherwise, native LVM code is used to detect signatures +(only MD RAID, swap and LUKS signatures are detected in this case.) +The LV is not wiped if the read only flag is set. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b + +.HP +.ad l +\fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.br +Controls zeroing of the first 4KiB of data in the new LV. +Default is \fBy\fP. +Snapshot COW volumes are always zeroed. +LV is not zeroed if the read only flag is set. +Warning: trying to mount an unzeroed LV can cause the system to hang. +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. +For lvcreate, the required VG positional arg may be +omitted when the VG name is included in another option, +e.g. --name VG/LV. + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. +LV followed by _ indicates that an LV of the +given type is required. (raid represents raid type) + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH ADVANCED USAGE +Alternate command forms, advanced command usage, and listing of all valid syntax for completeness. +.P +Create an LV that returns errors when used. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBerror\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create an LV that returns zeros when read. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBzero\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a linear LV. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBlinear\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a striped LV (also see lvcreate --stripes). +.br +.P +\fBlvcreate\fP \fB--type\fP \fBstriped\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a mirror LV (also see --type raid1). +.br +.P +\fBlvcreate\fP \fB--type\fP \fBmirror\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-m\fP|\fB--mirrors\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-R\fP|\fB--regionsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--mirrorlog\fP \fBcore\fP|\fBdisk\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a COW snapshot LV of an origin LV +.br +(also see --snapshot). +.br +.P +\fBlvcreate\fP \fB--type\fP \fBsnapshot\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fILV\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-s\fP|\fB--snapshot\fP ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a sparse COW snapshot LV of a virtual origin LV +.br +(also see --snapshot). +.br +.P +\fBlvcreate\fP \fB--type\fP \fBsnapshot\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] +.RS 5 + \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] \fIVG\fP +.RE +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-s\fP|\fB--snapshot\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a sparse COW snapshot LV of a virtual origin LV. +.br +.P +\fBlvcreate\fP \fB-s\fP|\fB--snapshot\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] +.RS 5 + \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] \fIVG\fP +.RE +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBsnapshot\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a thin pool (infers --type thin-pool). +.br +.P +\fBlvcreate\fP \fB-T\fP|\fB--thin\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBthin-pool\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a thin pool named by the --thinpool arg +.br +(infers --type thin-pool). +.br +.P +\fBlvcreate\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fB--thinpool\fP \fILV\fP\fI_new\fP \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBthin-pool\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a cache pool named by the --cachepool arg +.br +(variant, uses --cachepool in place of --name). +.br +.P +\fBlvcreate\fP \fB--type\fP \fBcache-pool\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] +.RS 5 + \fB--cachepool\fP \fILV\fP\fI_new\fP \fIVG\fP +.RE +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-H\fP|\fB--cache\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a thin LV in a thin pool. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBthin\fP \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] +.RS 5 + \fB--thinpool\fP \fILV\fP\fI_thinpool\fP \fIVG\fP +.RE +.br +.RS 4 +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV in a thin pool named in the first arg +.br +(variant, also see --thinpool for naming pool). +.br +.P +\fBlvcreate\fP \fB--type\fP \fBthin\fP \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] \fILV\fP\fI_thinpool\fP +.br +.RS 4 +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV in the thin pool named in the first arg +.br +(variant, infers --type thin, also see --thinpool for +.br +naming pool.) +.br +.P +\fBlvcreate\fP \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] \fILV\fP\fI_thinpool\fP +.br +.RS 4 +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV that is a snapshot of an existing thin LV. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBthin\fP \fILV\fP\fI_thin\fP +.br +.RS 4 +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV that is a snapshot of an existing thin LV +.br +(infers --type thin). +.br +.P +\fBlvcreate\fP \fB-T\fP|\fB--thin\fP \fILV\fP\fI_thin\fP +.br +.RS 4 +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV that is a snapshot of an external origin LV +.br +(infers --type thin). +.br +.P +\fBlvcreate\fP \fB-s\fP|\fB--snapshot\fP \fB--thinpool\fP \fILV\fP\fI_thinpool\fP \fILV\fP +.br +.RS 4 +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Create a thin LV, first creating a thin pool for it, +.br +where the new thin pool is named by the --thinpool arg +.br +(variant, infers --type thin). +.br +.P +\fBlvcreate\fP \fB-T\fP|\fB--thin\fP \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] +.RS 5 + \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fB--thinpool\fP \fILV\fP\fI_new\fP +.RE +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a thin LV, first creating a thin pool for it, +.br +where the new thin pool is named in the first arg, +.br +or the new thin pool name is generated when the first +.br +arg is a VG name. +.br +.P +\fBlvcreate\fP \fB--type\fP \fBthin\fP \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] +.RS 5 + \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP|\fILV\fP\fI_new\fP +.RE +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a thin LV, first creating a thin pool for it, +.br +where the new thin pool is named in the first arg, +.br +or the new thin pool name is generated when the first +.br +arg is a VG name (variant, infers --type thin). +.br +.P +\fBlvcreate\fP \fB-T\fP|\fB--thin\fP \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] +.RS 5 + \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fIVG\fP|\fILV\fP\fI_new\fP +.RE +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a thin LV, first creating a thin pool for it +.br +(infers --type thin). +.br +Create a sparse snapshot of a virtual origin LV +.br +(infers --type snapshot). +.br +Chooses --type thin or --type snapshot according to +.br +config setting sparse_segtype_default. +.br +.P +\fBlvcreate\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fB-V\fP|\fB--virtualsize\fP \fISize\fP[m|UNIT] \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-T\fP|\fB--thin\fP ] +.ad b +.br +.ad l +[ \fB-s\fP|\fB--snapshot\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBthin\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--discards\fP \fBpassdown\fP|\fBnopassdown\fP|\fBignore\fP ] +.ad b +.br +.ad l +[ \fB--errorwhenfull\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a cache LV, first creating a new origin LV, +.br +then combining it with the existing cache pool named +.br +by the --cachepool arg (variant, infers --type cache). +.br +.P +\fBlvcreate\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fB--cachepool\fP \fILV\fP\fI_cachepool\fP \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-H\fP|\fB--cache\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--type\fP \fBcache\fP ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Create a cache LV, first creating a new origin LV, +.br +then combining it with the existing cache pool named +.br +in the first arg (variant, also use --cachepool). +.br +.P +\fBlvcreate\fP \fB--type\fP \fBcache\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fILV\fP\fI_cachepool\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-H\fP|\fB--cache\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +When LV is a cache pool, create a cache LV, +.br +first creating a new origin LV, then combining it with +.br +the existing cache pool named in the first arg +.br +(variant, infers --type cache, also use --cachepool). +.br +When LV is not a cache pool, convert the specified LV +.br +to type cache after creating a new cache pool LV to use +.br +(use lvconvert). +.br +.P +\fBlvcreate\fP \fB-H\fP|\fB--cache\fP \fB-L\fP|\fB--size\fP \fISize\fP[m|UNIT] \fILV\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP \fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--chunksize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--cachemode\fP \fBwritethrough\fP|\fBwriteback\fP|\fBpassthrough\fP ] +.ad b +.br +.ad l +[ \fB--cachepolicy\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachesettings\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--cachemetadataformat\fP \fBauto\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadataspare\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +.SH EXAMPLES + +Create a striped LV with 3 stripes, a stripe size of 8KiB and a size of 100MiB. +The LV name is chosen by lvcreate. +.br +.B lvcreate \-i 3 \-I 8 \-L 100m vg00 + +Create a raid1 LV with two images, and a useable size of 500 MiB. This +operation requires two devices, one for each mirror image. RAID metadata +(superblock and bitmap) is also included on the two devices. +.br +.B lvcreate \-\-type raid1 \-m1 \-L 500m \-n mylv vg00 + +Create a mirror LV with two images, and a useable size of 500 MiB. +This operation requires three devices: two for mirror images and +one for a disk log. +.br +.B lvcreate \-\-type mirror \-m1 \-L 500m \-n mylv vg00 + +Create a mirror LV with 2 images, and a useable size of 500 MiB. +This operation requires 2 devices because the log is in memory. +.br +.B lvcreate \-\-type mirror \-m1 \-\-mirrorlog core \-L 500m \-n mylv vg00 + +Create a copy\-on\-write snapshot of an LV: +.br +.B lvcreate \-\-snapshot \-\-size 100m \-\-name mysnap vg00/mylv + +Create a copy\-on\-write snapshot with a size sufficient +for overwriting 20% of the size of the original LV. +.br +.B lvcreate \-s \-l 20%ORIGIN \-n mysnap vg00/mylv + +Create a sparse LV with 1TiB of virtual space, and actual space just under +100MiB. +.br +.B lvcreate \-\-snapshot \-\-virtualsize 1t \-\-size 100m \-\-name mylv vg00 + +Create a linear LV with a usable size of 64MiB on specific physical extents. +.br +.B lvcreate \-L 64m \-n mylv vg00 /dev/sda:0\-7 /dev/sdb:0\-7 + +Create a RAID5 LV with a usable size of 5GiB, 3 stripes, a stripe size of +64KiB, using a total of 4 devices (including one for parity). +.br +.B lvcreate \-\-type raid5 \-L 5G \-i 3 \-I 64 \-n mylv vg00 + +Create a RAID5 LV using all of the free space in the VG and spanning all the +PVs in the VG (note that the command will fail if there are more than 8 PVs in +the VG, in which case \fB\-i 7\fP must be used to get to the current maximum of +8 devices including parity for RaidLVs). +.br +.B lvcreate \-\-config allocation/raid_stripe_all_devices=1 +.RS +.B \-\-type raid5 \-l 100%FREE \-n mylv vg00 +.RE + +Create RAID10 LV with a usable size of 5GiB, using 2 stripes, each on +a two-image mirror. (Note that the \fB-i\fP and \fB-m\fP arguments behave +differently: +\fB-i\fP specifies the total number of stripes, +but \fB-m\fP specifies the number of images in addition +to the first image). +.br +.B lvcreate \-\-type raid10 \-L 5G \-i 2 \-m 1 \-n mylv vg00 + +Create a 1TiB thin LV, first creating a new thin pool for it, where +the thin pool has 100MiB of space, uses 2 stripes, has a 64KiB stripe +size, and 256KiB chunk size. +.br +.B lvcreate \-\-type thin \-\-name mylv \-\-thinpool mypool +.RS +.B \-V 1t \-L 100m \-i 2 \-I 64 \-c 256 vg00 +.RE + +Create a thin snapshot of a thin LV (the size option must not be +used, otherwise a copy-on-write snapshot would be created). +.br +.B lvcreate \-\-snapshot \-\-name mysnap vg00/thinvol + +Create a thin snapshot of the read-only inactive LV named "origin" +which becomes an external origin for the thin snapshot LV. +.br +.B lvcreate \-\-snapshot \-\-name mysnap \-\-thinpool mypool vg00/origin + +Create a cache pool from a fast physical device. The cache pool can +then be used to cache an LV. +.br +.B lvcreate \-\-type cache-pool \-L 1G \-n my_cpool vg00 /dev/fast1 + +Create a cache LV, first creating a new origin LV on a slow physical device, +then combining the new origin LV with an existing cache pool. +.br +.B lvcreate \-\-type cache \-\-cachepool my_cpool +.RS +.B \-L 100G \-n mylv vg00 /dev/slow1 +.RE + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvdisplay.8.des b/man/lvdisplay.8.des deleted file mode 100644 index 48552cc..0000000 --- a/man/lvdisplay.8.des +++ /dev/null @@ -1,5 +0,0 @@ -lvdisplay shows the attributes of LVs, like size, read/write status, -snapshot information, etc. - -\fBlvs\fP(8) is a preferred alternative that shows the same information -and more, using a more compact and configurable output format. diff --git a/man/lvdisplay.8_des b/man/lvdisplay.8_des new file mode 100644 index 0000000..48552cc --- /dev/null +++ b/man/lvdisplay.8_des @@ -0,0 +1,5 @@ +lvdisplay shows the attributes of LVs, like size, read/write status, +snapshot information, etc. + +\fBlvs\fP(8) is a preferred alternative that shows the same information +and more, using a more compact and configurable output format. diff --git a/man/lvdisplay.8_end b/man/lvdisplay.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvdisplay.8_pregen b/man/lvdisplay.8_pregen new file mode 100644 index 0000000..10d45ae --- /dev/null +++ b/man/lvdisplay.8_pregen @@ -0,0 +1,639 @@ +.TH LVDISPLAY 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvdisplay \- Display information about a logical volume +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvdisplay\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +lvdisplay shows the attributes of LVs, like size, read/write status, +snapshot information, etc. + +\fBlvs\fP(8) is a preferred alternative that shows the same information +and more, using a more compact and configurable output format. + +.P +.SH USAGE +.br +.P +. +\fBlvdisplay\fP +.br +.RS 4 +.ad l +[ \fB-a\fP|\fB--all\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--colon\fP ] +.ad b +.br +.ad l +[ \fB-C\fP|\fB--columns\fP ] +.ad b +.br +.ad l +[ \fB-H\fP|\fB--history\fP ] +.ad b +.br +.ad l +[ \fB-m\fP|\fB--maps\fP ] +.ad b +.br +.ad l +[ \fB-o\fP|\fB--options\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-O\fP|\fB--sort\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--aligned\fP ] +.ad b +.br +.ad l +[ \fB--binary\fP ] +.ad b +.br +.ad l +[ \fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP ] +.ad b +.br +.ad l +[ \fB--foreign\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--logonly\fP ] +.ad b +.br +.ad l +[ \fB--noheadings\fP ] +.ad b +.br +.ad l +[ \fB--nosuffix\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--segments\fP ] +.ad b +.br +.ad l +[ \fB--separator\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--shared\fP ] +.ad b +.br +.ad l +[ \fB--unbuffered\fP ] +.ad b +.br +.ad l +[ \fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fILV\fP|\fITag\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--aligned\fP +.br +Use with --separator to align the output columns +.ad b + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +Show information about internal LVs. +These are components of normal LVs, such as mirrors, +which are not independently accessible, e.g. not mountable. +.ad b + +.HP +.ad l +\fB--binary\fP +.br +Use binary values "0" or "1" instead of descriptive literal values +for columns that have exactly two valid values to report (not counting +the "unknown" value which denotes that the value could not be determined). +.ad b + +.HP +.ad l +\fB-c\fP|\fB--colon\fP +.br +Generate colon separated output for easier parsing in scripts or programs. +Also see vgs(8) which provides considerably more control over the output. +.ad b + +.HP +.ad l +\fB-C\fP|\fB--columns\fP +.br +Display output in columns, the equivalent of vgs(8). +Options listed are the same as options given in vgs(8). +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--foreign\fP +.br +Report/display foreign VGs that would otherwise be skipped. +See lvmsystemid(7) for more information about foreign VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-H\fP|\fB--history\fP +.br +Include historical LVs in the output. +(This has no effect unless LVs were removed while +lvm.conf metadata/record_lvs_history was enabled. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--logonly\fP +.br +Suppress command report and display only log report. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-m\fP|\fB--maps\fP +.br +Display the mapping of logical extents to PVs and physical extents. +To map physical extents to logical extents use: +pvs --segments -o+lv_name,seg_start_pe,segtype +.ad b + +.HP +.ad l +\fB--noheadings\fP +.br +Suppress the headings line that is normally the first line of output. +Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--nosuffix\fP +.br +Suppress the suffix on output sizes. Use with --units +(except h and H) if processing the output. +.ad b + +.HP +.ad l +\fB-o\fP|\fB--options\fP \fIString\fP +.br +Comma-separated, ordered list of fields to display in columns. +String arg syntax is: [+|-|#]Field1[,Field2 ...] +The prefix \fB+\fP will append the specified fields to the default fields, +\fB-\fP will remove the specified fields from the default fields, and +\fB#\fP will compact specified fields (removing them when empty for all rows.) +Use \fB-o help\fP to view the list of all available fields. +The -o option can be repeated, providing several lists. +These lists are evaluated from left to right. +Use field name \fBlv_all\fP to view all LV fields, +\fBvg_all\fP all VG fields, +\fBpv_all\fP all PV fields, +\fBpvseg_all\fP all PV segment fields, +\fBseg_all\fP all LV segment fields, and +\fBpvseg_all\fP all PV segment columns. +See the lvm.conf report section for more config options. +See lvmreport(7) for more information about reporting. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--segments\fP +.br +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB--separator\fP \fIString\fP +.br +String to use to separate each column. Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--shared\fP +.br +Report/display shared VGs that would otherwise be skipped when +lvmlockd is not being used on the host. +See lvmlockd(8) for more information about shared VGs. +.ad b + +.HP +.ad l +\fB-O\fP|\fB--sort\fP \fIString\fP +.br +Comma-separated ordered list of columns to sort by. Replaces the default +selection. Precede any column with \fB-\fP for a reverse sort on that column. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--unbuffered\fP +.br +Produce output immediately without sorting or aligning the columns properly. +.ad b + +.HP +.ad l +\fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP +.br +All sizes are output in these units: +human-(r)eadable with '<' rounding indicator, +(h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, +(g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. +Capitalise to use multiples of 1000 (S.I.) instead of 1024. +Custom units can be specified, e.g. --units 3M. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvextend.8.des b/man/lvextend.8.des deleted file mode 100644 index 4c0575d..0000000 --- a/man/lvextend.8.des +++ /dev/null @@ -1,12 +0,0 @@ -lvextend extends the size of an LV. This requires allocating logical -extents from the VG's free physical extents. If the extension adds a new -LV segment, the new segment will use the existing segment type of the LV. - -Extending a copy\-on\-write snapshot LV adds space for COW blocks. - -Use \fBlvconvert\fP(8) to change the number of data images in a RAID or -mirrored LV. - -In the usage section below, \fB--size\fP \fISize\fP can be replaced -with \fB--extents\fP \fINumber\fP. See both descriptions -the options section. diff --git a/man/lvextend.8.end b/man/lvextend.8.end deleted file mode 100644 index 6d197de..0000000 --- a/man/lvextend.8.end +++ /dev/null @@ -1,16 +0,0 @@ -.SH EXAMPLES - -Extend the size of an LV by 54MiB, using a specific PV. -.br -.B lvextend \-L +54 vg01/lvol10 /dev/sdk3 - -Extend the size of an LV by the amount of free -space on PV /dev/sdk3. This is equivalent to specifying -"\-l +100%PVS" on the command line. -.br -.B lvextend vg01/lvol01 /dev/sdk3 - -Extend an LV by 16MiB using specific physical extents. -.br -.B lvextend \-L+16m vg01/lvol01 /dev/sda:8\-9 /dev/sdb:8\-9 - diff --git a/man/lvextend.8_des b/man/lvextend.8_des new file mode 100644 index 0000000..4c0575d --- /dev/null +++ b/man/lvextend.8_des @@ -0,0 +1,12 @@ +lvextend extends the size of an LV. This requires allocating logical +extents from the VG's free physical extents. If the extension adds a new +LV segment, the new segment will use the existing segment type of the LV. + +Extending a copy\-on\-write snapshot LV adds space for COW blocks. + +Use \fBlvconvert\fP(8) to change the number of data images in a RAID or +mirrored LV. + +In the usage section below, \fB--size\fP \fISize\fP can be replaced +with \fB--extents\fP \fINumber\fP. See both descriptions +the options section. diff --git a/man/lvextend.8_end b/man/lvextend.8_end new file mode 100644 index 0000000..6d197de --- /dev/null +++ b/man/lvextend.8_end @@ -0,0 +1,16 @@ +.SH EXAMPLES + +Extend the size of an LV by 54MiB, using a specific PV. +.br +.B lvextend \-L +54 vg01/lvol10 /dev/sdk3 + +Extend the size of an LV by the amount of free +space on PV /dev/sdk3. This is equivalent to specifying +"\-l +100%PVS" on the command line. +.br +.B lvextend vg01/lvol01 /dev/sdk3 + +Extend an LV by 16MiB using specific physical extents. +.br +.B lvextend \-L+16m vg01/lvol01 /dev/sda:8\-9 /dev/sdb:8\-9 + diff --git a/man/lvextend.8_pregen b/man/lvextend.8_pregen new file mode 100644 index 0000000..92e5796 --- /dev/null +++ b/man/lvextend.8_pregen @@ -0,0 +1,781 @@ +.TH LVEXTEND 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvextend \- Add space to a logical volume +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvextend\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.P +.ad l + \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.ad b +.br +.ad l + \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--commandprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--config\fP \fIString\fP +.ad b +.br +.ad l + \fB-d\fP|\fB--debug\fP +.ad b +.br +.ad l + \fB--driverloaded\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-l\fP|\fB--extents\fP [\fB+\fP]\fINumber\fP[PERCENT] +.ad b +.br +.ad l + \fB-f\fP|\fB--force\fP +.ad b +.br +.ad l + \fB-h\fP|\fB--help\fP +.ad b +.br +.ad l + \fB--longhelp\fP +.ad b +.br +.ad l + \fB-m\fP|\fB--mirrors\fP \fINumber\fP +.ad b +.br +.ad l + \fB-n\fP|\fB--nofsck\fP +.ad b +.br +.ad l + \fB--nosync\fP +.ad b +.br +.ad l + \fB--noudevsync\fP +.ad b +.br +.ad l + \fB--poolmetadatasize\fP [\fB+\fP]\fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP +.ad b +.br +.ad l + \fB-q\fP|\fB--quiet\fP +.ad b +.br +.ad l + \fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.ad b +.br +.ad l + \fB-r\fP|\fB--resizefs\fP +.ad b +.br +.ad l + \fB-L\fP|\fB--size\fP [\fB+\fP]\fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB-i\fP|\fB--stripes\fP \fINumber\fP +.ad b +.br +.ad l + \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB-t\fP|\fB--test\fP +.ad b +.br +.ad l + \fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP +.ad b +.br +.ad l + \fB--usepolicies\fP +.ad b +.br +.ad l + \fB-v\fP|\fB--verbose\fP +.ad b +.br +.ad l + \fB--version\fP +.ad b +.br +.ad l + \fB-y\fP|\fB--yes\fP +.ad b + +.P + +.SH DESCRIPTION +lvextend extends the size of an LV. This requires allocating logical +extents from the VG's free physical extents. If the extension adds a new +LV segment, the new segment will use the existing segment type of the LV. + +Extending a copy\-on\-write snapshot LV adds space for COW blocks. + +Use \fBlvconvert\fP(8) to change the number of data images in a RAID or +mirrored LV. + +In the usage section below, \fB--size\fP \fISize\fP can be replaced +with \fB--extents\fP \fINumber\fP. See both descriptions +the options section. + +.P +.SH USAGE +.br +.P +. +Extend an LV by a specified size. +.br +.P +\fBlvextend\fP \fB-L\fP|\fB--size\fP [\fB+\fP]\fISize\fP[m|UNIT] \fILV\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP [\fB+\fP]\fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--resizefs\fP ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP [\fB+\fP]\fISize\fP[m|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Extend an LV by specified PV extents. +.br +.P +\fBlvextend\fP \fILV\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB-r\fP|\fB--resizefs\fP ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Extend a pool metadata SubLV by a specified size. +.br +.P +\fBlvextend\fP \fB--poolmetadatasize\fP [\fB+\fP]\fISize\fP[m|UNIT] \fILV\fP\fI_thinpool\fP +.br +.RS 4 +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Extend an LV according to a predefined policy. +.br +.P +\fBlvextend\fP \fB--usepolicies\fP \fILV\fP\fI_snapshot_thinpool\fP +.br +.RS 4 +.ad l +[ \fB-r\fP|\fB--resizefs\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-m\fP|\fB--mirrors\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-n\fP|\fB--nofsck\fP ] +.ad b +.br +.ad l +[ \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP ] +.ad b +.br +.ad l +[ \fB--nosync\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--extents\fP [\fB+\fP]\fINumber\fP[PERCENT] +.br +Specifies the new size of the LV in logical extents. +The --size and --extents options are alternate methods of specifying size. +The total number of physical extents used will be +greater when redundant data is needed for RAID levels. +An alternate syntax allows the size to be determined indirectly +as a percentage of the size of a related VG, LV, or set of PVs. The +suffix \fB%VG\fP denotes the total size of the VG, the suffix \fB%FREE\fP +the remaining free space in the VG, and the suffix \fB%PVS\fP the free +space in the specified PVs. For a snapshot, the size +can be expressed as a percentage of the total size of the origin LV +with the suffix \fB%ORIGIN\fP (\fB100%ORIGIN\fP provides space for +the whole origin). +When expressed as a percentage, the size defines an upper limit for the +number of logical extents in the new LV. The precise number of logical +extents in the new LV is not determined until the command has completed. +When the plus \fB+\fP or minus \fB-\fP prefix is used, +the value is not an absolute size, but is relative and added or subtracted +from the current size. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-m\fP|\fB--mirrors\fP \fINumber\fP +.br +Not used. +.ad b + +.HP +.ad l +\fB-n\fP|\fB--nofsck\fP +.br +Do not perform fsck before resizing filesystem when filesystem +requires it. You may need to use --force to proceed with +this option. +.ad b + +.HP +.ad l +\fB--nosync\fP +.br +Causes the creation of mirror, raid1, raid4, raid5 and raid10 to skip the +initial synchronization. In case of mirror, raid1 and raid10, any data +written afterwards will be mirrored, but the original contents will not be +copied. In case of raid4 and raid5, no parity blocks will be written, +though any data written afterwards will cause parity blocks to be stored. +This is useful for skipping a potentially long and resource intensive initial +sync of an empty mirror/raid1/raid4/raid5 and raid10 LV. +This option is not valid for raid6, because raid6 relies on proper parity +(P and Q Syndromes) being created during initial synchronization in order +to reconstruct proper user date in case of device failures. +raid0 and raid0_meta do not provide any data copies or parity support +and thus do not support initial synchronization. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB--poolmetadatasize\fP [\fB+\fP]\fISize\fP[m|UNIT] +.br +Specifies the new size of the pool metadata LV. +The plus prefix \fB+\fP can be used, in which case +the value is added to the current size. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-r\fP|\fB--resizefs\fP +.br +Resize underlying filesystem together with the LV using fsadm(8). +.ad b + +.HP +.ad l +\fB-L\fP|\fB--size\fP [\fB+\fP]\fISize\fP[m|UNIT] +.br +Specifies the new size of the LV. +The --size and --extents options are alternate methods of specifying size. +The total number of physical extents used will be +greater when redundant data is needed for RAID levels. +When the plus \fB+\fP or minus \fB-\fP prefix is used, +the value is not an absolute size, but is relative and added or subtracted +from the current size. +.ad b + +.HP +.ad l +\fB-i\fP|\fB--stripes\fP \fINumber\fP +.br +Specifies the number of stripes in a striped LV. This is the number of +PVs (devices) that a striped LV is spread across. Data that +appears sequential in the LV is spread across multiple devices in units of +the stripe size (see --stripesize). This does not change existing +allocated space, but only applies to space being allocated by the command. +When creating a RAID 4/5/6 LV, this number does not include the extra +devices that are required for parity. The largest number depends on +the RAID type (raid0: 64, raid10: 32, raid4/5: 63, raid6: 62), and +when unspecified, the default depends on the RAID type +(raid0: 2, raid10: 4, raid4/5: 3, raid6: 5.) +To stripe a new raid LV across all PVs by default, +see lvm.conf allocation/raid_stripe_all_devices. +.ad b + +.HP +.ad l +\fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] +.br +The amount of data that is written to one device before +moving to the next in a striped LV. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP +.br +The LV type, also known as "segment type" or "segtype". +See usage descriptions for the specific ways to use these types. +For more information about redundancy and performance (\fBraid\fP, \fBmirror\fP, \fBstriped\fP, \fBlinear\fP) see \fBlvmraid\fP(7). +For thin provisioning (\fBthin\fP, \fBthin-pool\fP) see \fBlvmthin\fP(7). +For performance caching (\fBcache\fP, \fBcache-pool\fP) see \fBlvmcache\fP(7). +For copy-on-write snapshots (\fBsnapshot\fP) see usage definitions. +Several commands omit an explicit type option because the type +is inferred from other options or shortcuts +(e.g. --stripes, --mirrors, --snapshot, --virtualsize, --thin, --cache). +Use inferred types with care because it can lead to unexpected results. +.ad b + +.HP +.ad l +\fB--usepolicies\fP +.br +Perform an operation according to the policy configured in lvm.conf +or a profile. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. +LV followed by _ indicates that an LV of the +given type is required. (raid represents raid type) + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Extend the size of an LV by 54MiB, using a specific PV. +.br +.B lvextend \-L +54 vg01/lvol10 /dev/sdk3 + +Extend the size of an LV by the amount of free +space on PV /dev/sdk3. This is equivalent to specifying +"\-l +100%PVS" on the command line. +.br +.B lvextend vg01/lvol01 /dev/sdk3 + +Extend an LV by 16MiB using specific physical extents. +.br +.B lvextend \-L+16m vg01/lvol01 /dev/sda:8\-9 /dev/sdb:8\-9 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvm-config.8.des b/man/lvm-config.8.des deleted file mode 100644 index 1d36566..0000000 --- a/man/lvm-config.8.des +++ /dev/null @@ -1,5 +0,0 @@ -This command is the same as \fBlvmconfig\fP(8). - -lvm config produces formatted output from the LVM configuration tree. The -sources of the configuration data include \fBlvm.conf\fP(5) and command -line settings from \-\-config. diff --git a/man/lvm-config.8_des b/man/lvm-config.8_des new file mode 100644 index 0000000..1d36566 --- /dev/null +++ b/man/lvm-config.8_des @@ -0,0 +1,5 @@ +This command is the same as \fBlvmconfig\fP(8). + +lvm config produces formatted output from the LVM configuration tree. The +sources of the configuration data include \fBlvm.conf\fP(5) and command +line settings from \-\-config. diff --git a/man/lvm-config.8_end b/man/lvm-config.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvm-config.8_pregen b/man/lvm-config.8_pregen new file mode 100644 index 0000000..7223fd2 --- /dev/null +++ b/man/lvm-config.8_pregen @@ -0,0 +1,522 @@ +.TH LVM CONFIG 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvm config \- Display and manipulate configuration information +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvm config\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +This command is the same as \fBlvmconfig\fP(8). + +lvm config produces formatted output from the LVM configuration tree. The +sources of the configuration data include \fBlvm.conf\fP(5) and command +line settings from \-\-config. + +.P +.SH USAGE +.br +.P +. +\fBlvm config\fP +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--file\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-l\fP|\fB--list\fP ] +.ad b +.br +.ad l +[ \fB--atversion\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--typeconfig\fP \fBcurrent\fP|\fBdefault\fP|\fBdiff\fP|\fBfull\fP|\fBlist\fP|\fBmissing\fP|\fBnew\fP|\fBprofilable\fP|\fBprofilable-command\fP|\fBprofilable-metadata\fP ] +.ad b +.br +.ad l +[ \fB--ignoreadvanced\fP ] +.ad b +.br +.ad l +[ \fB--ignoreunsupported\fP ] +.ad b +.br +.ad l +[ \fB--ignorelocal\fP ] +.ad b +.br +.ad l +[ \fB--mergedconfig\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--sinceversion\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--showdeprecated\fP ] +.ad b +.br +.ad l +[ \fB--showunsupported\fP ] +.ad b +.br +.ad l +[ \fB--validate\fP ] +.ad b +.br +.ad l +[ \fB--withsummary\fP ] +.ad b +.br +.ad l +[ \fB--withcomments\fP ] +.ad b +.br +.ad l +[ \fB--withspaces\fP ] +.ad b +.br +.ad l +[ \fB--unconfigured\fP ] +.ad b +.br +.ad l +[ \fB--withversions\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIString\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--atversion\fP \fIString\fP +.br +Specify an LVM version in x.y.z format where x is the major version, +the y is the minor version and z is the patchlevel (e.g. 2.2.106). +When configuration is displayed, the configuration settings recognized +at this LVM version will be considered only. This can be used +to display a configuration that a certain LVM version understands and +which does not contain any newer settings for which LVM would +issue a warning message when checking the configuration. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--file\fP \fIString\fP +.br +Write output to the named file. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignoreadvanced\fP +.br +Exclude advanced configuration settings from the output. +.ad b + +.HP +.ad l +\fB--ignorelocal\fP +.br +Ignore local section. +.ad b + +.HP +.ad l +\fB--ignoreunsupported\fP +.br +Exclude unsupported configuration settings from the output. These settings are +either used for debugging and development purposes only or their support is not +yet complete and they are not meant to be used in production. The \fBcurrent\fP +and \fBdiff\fP types include unsupported settings in their output by default, +all the other types ignore unsupported settings. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--list\fP +.br +List config settings with summarizing comment. This is the same as using +options --typeconfig list --withsummary. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--mergedconfig\fP +.br +When the command is run with --config +and/or --commandprofile (or using LVM_COMMAND_PROFILE +environment variable), --profile, or --metadataprofile, +merge all the contents of the "config cascade" before displaying it. +Without merging, only the configuration at the front of the +cascade is displayed. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--metadataprofile\fP \fIString\fP +.br +The metadata profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--showdeprecated\fP +.br +Include deprecated configuration settings in the output. These settings +are deprecated after a certain version. If a concrete version is specified +with --atversion, deprecated settings are automatically included +if the specified version is lower than the version in which the settings were +deprecated. The current and diff types include deprecated settings +in their output by default, all the other types ignore deprecated settings. +.ad b + +.HP +.ad l +\fB--showunsupported\fP +.br +Include unsupported configuration settings in the output. These settings +are either used for debugging or development purposes only, or their support +is not yet complete and they are not meant to be used in production. The +current and diff types include unsupported settings in their +output by default, all the other types ignore unsupported settings. +.ad b + +.HP +.ad l +\fB--sinceversion\fP \fIString\fP +.br +Specify an LVM version in x.y.z format where x is the major version, +the y is the minor version and z is the patchlevel (e.g. 2.2.106). +This option is currently applicable only with --typeconfig new +to display all configuration settings introduced since given version. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--typeconfig\fP \fBcurrent\fP|\fBdefault\fP|\fBdiff\fP|\fBfull\fP|\fBlist\fP|\fBmissing\fP|\fBnew\fP|\fBprofilable\fP|\fBprofilable-command\fP|\fBprofilable-metadata\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB--unconfigured\fP +.br +Internal option used for generating config file during build. +.ad b + +.HP +.ad l +\fB--validate\fP +.br +Validate current configuration used and exit with appropriate +return code. The validation is done only for the configuration +at the front of the "config cascade". To validate the whole +merged configuration tree, also use --mergedconfig. +The validation is done even if lvm.conf config/checks is disabled. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB--withcomments\fP +.br +Display a full comment for each configuration node. For deprecated +settings, also display comments about deprecation. +.ad b + +.HP +.ad l +\fB--withspaces\fP +.br +Where appropriate, add more spaces in output for better readability. +.ad b + +.HP +.ad l +\fB--withsummary\fP +.br +Display a one line comment for each configuration node. +.ad b + +.HP +.ad l +\fB--withversions\fP +.br +Also display a comment containing the version of introduction for +each configuration node. If the setting is deprecated, also display +the version since which it is deprecated. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvm-dumpconfig.8.des b/man/lvm-dumpconfig.8.des deleted file mode 100644 index 18593fb..0000000 --- a/man/lvm-dumpconfig.8.des +++ /dev/null @@ -1,5 +0,0 @@ -This command is the same as \fBlvmconfig\fP(8). - -lvm dumpconfig produces formatted output from the LVM configuration tree. The -sources of the configuration data include \fBlvm.conf\fP(5) and command -line settings from \-\-config. diff --git a/man/lvm-dumpconfig.8_des b/man/lvm-dumpconfig.8_des new file mode 100644 index 0000000..18593fb --- /dev/null +++ b/man/lvm-dumpconfig.8_des @@ -0,0 +1,5 @@ +This command is the same as \fBlvmconfig\fP(8). + +lvm dumpconfig produces formatted output from the LVM configuration tree. The +sources of the configuration data include \fBlvm.conf\fP(5) and command +line settings from \-\-config. diff --git a/man/lvm-dumpconfig.8_end b/man/lvm-dumpconfig.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvm-dumpconfig.8_pregen b/man/lvm-dumpconfig.8_pregen new file mode 100644 index 0000000..acc54ca --- /dev/null +++ b/man/lvm-dumpconfig.8_pregen @@ -0,0 +1,522 @@ +.TH LVM DUMPCONFIG 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvm dumpconfig \- Display and manipulate configuration information +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvm dumpconfig\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +This command is the same as \fBlvmconfig\fP(8). + +lvm dumpconfig produces formatted output from the LVM configuration tree. The +sources of the configuration data include \fBlvm.conf\fP(5) and command +line settings from \-\-config. + +.P +.SH USAGE +.br +.P +. +\fBlvm dumpconfig\fP +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--file\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-l\fP|\fB--list\fP ] +.ad b +.br +.ad l +[ \fB--atversion\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--typeconfig\fP \fBcurrent\fP|\fBdefault\fP|\fBdiff\fP|\fBfull\fP|\fBlist\fP|\fBmissing\fP|\fBnew\fP|\fBprofilable\fP|\fBprofilable-command\fP|\fBprofilable-metadata\fP ] +.ad b +.br +.ad l +[ \fB--ignoreadvanced\fP ] +.ad b +.br +.ad l +[ \fB--ignoreunsupported\fP ] +.ad b +.br +.ad l +[ \fB--ignorelocal\fP ] +.ad b +.br +.ad l +[ \fB--mergedconfig\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--sinceversion\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--showdeprecated\fP ] +.ad b +.br +.ad l +[ \fB--showunsupported\fP ] +.ad b +.br +.ad l +[ \fB--validate\fP ] +.ad b +.br +.ad l +[ \fB--withsummary\fP ] +.ad b +.br +.ad l +[ \fB--withcomments\fP ] +.ad b +.br +.ad l +[ \fB--withspaces\fP ] +.ad b +.br +.ad l +[ \fB--unconfigured\fP ] +.ad b +.br +.ad l +[ \fB--withversions\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIString\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--atversion\fP \fIString\fP +.br +Specify an LVM version in x.y.z format where x is the major version, +the y is the minor version and z is the patchlevel (e.g. 2.2.106). +When configuration is displayed, the configuration settings recognized +at this LVM version will be considered only. This can be used +to display a configuration that a certain LVM version understands and +which does not contain any newer settings for which LVM would +issue a warning message when checking the configuration. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--file\fP \fIString\fP +.br +Write output to the named file. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignoreadvanced\fP +.br +Exclude advanced configuration settings from the output. +.ad b + +.HP +.ad l +\fB--ignorelocal\fP +.br +Ignore local section. +.ad b + +.HP +.ad l +\fB--ignoreunsupported\fP +.br +Exclude unsupported configuration settings from the output. These settings are +either used for debugging and development purposes only or their support is not +yet complete and they are not meant to be used in production. The \fBcurrent\fP +and \fBdiff\fP types include unsupported settings in their output by default, +all the other types ignore unsupported settings. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--list\fP +.br +List config settings with summarizing comment. This is the same as using +options --typeconfig list --withsummary. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--mergedconfig\fP +.br +When the command is run with --config +and/or --commandprofile (or using LVM_COMMAND_PROFILE +environment variable), --profile, or --metadataprofile, +merge all the contents of the "config cascade" before displaying it. +Without merging, only the configuration at the front of the +cascade is displayed. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--metadataprofile\fP \fIString\fP +.br +The metadata profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--showdeprecated\fP +.br +Include deprecated configuration settings in the output. These settings +are deprecated after a certain version. If a concrete version is specified +with --atversion, deprecated settings are automatically included +if the specified version is lower than the version in which the settings were +deprecated. The current and diff types include deprecated settings +in their output by default, all the other types ignore deprecated settings. +.ad b + +.HP +.ad l +\fB--showunsupported\fP +.br +Include unsupported configuration settings in the output. These settings +are either used for debugging or development purposes only, or their support +is not yet complete and they are not meant to be used in production. The +current and diff types include unsupported settings in their +output by default, all the other types ignore unsupported settings. +.ad b + +.HP +.ad l +\fB--sinceversion\fP \fIString\fP +.br +Specify an LVM version in x.y.z format where x is the major version, +the y is the minor version and z is the patchlevel (e.g. 2.2.106). +This option is currently applicable only with --typeconfig new +to display all configuration settings introduced since given version. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--typeconfig\fP \fBcurrent\fP|\fBdefault\fP|\fBdiff\fP|\fBfull\fP|\fBlist\fP|\fBmissing\fP|\fBnew\fP|\fBprofilable\fP|\fBprofilable-command\fP|\fBprofilable-metadata\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB--unconfigured\fP +.br +Internal option used for generating config file during build. +.ad b + +.HP +.ad l +\fB--validate\fP +.br +Validate current configuration used and exit with appropriate +return code. The validation is done only for the configuration +at the front of the "config cascade". To validate the whole +merged configuration tree, also use --mergedconfig. +The validation is done even if lvm.conf config/checks is disabled. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB--withcomments\fP +.br +Display a full comment for each configuration node. For deprecated +settings, also display comments about deprecation. +.ad b + +.HP +.ad l +\fB--withspaces\fP +.br +Where appropriate, add more spaces in output for better readability. +.ad b + +.HP +.ad l +\fB--withsummary\fP +.br +Display a one line comment for each configuration node. +.ad b + +.HP +.ad l +\fB--withversions\fP +.br +Also display a comment containing the version of introduction for +each configuration node. If the setting is deprecated, also display +the version since which it is deprecated. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvm-fullreport.8.des b/man/lvm-fullreport.8.des deleted file mode 100644 index f350a0a..0000000 --- a/man/lvm-fullreport.8.des +++ /dev/null @@ -1,6 +0,0 @@ -lvm fullreport produces formatted output about PVs, PV segments, VGs, LVs -and LV segments. The information is all gathered together for each VG -(under a per-VG lock) so it is consistent. Information gathered from -separate calls to \fBvgs\fP, \fBpvs\fP, and \fBlvs\fP can be inconsistent -if information changes between commands. - diff --git a/man/lvm-fullreport.8_des b/man/lvm-fullreport.8_des new file mode 100644 index 0000000..f350a0a --- /dev/null +++ b/man/lvm-fullreport.8_des @@ -0,0 +1,6 @@ +lvm fullreport produces formatted output about PVs, PV segments, VGs, LVs +and LV segments. The information is all gathered together for each VG +(under a per-VG lock) so it is consistent. Information gathered from +separate calls to \fBvgs\fP, \fBpvs\fP, and \fBlvs\fP can be inconsistent +if information changes between commands. + diff --git a/man/lvm-fullreport.8_end b/man/lvm-fullreport.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvm-fullreport.8_pregen b/man/lvm-fullreport.8_pregen new file mode 100644 index 0000000..74f8dd3 --- /dev/null +++ b/man/lvm-fullreport.8_pregen @@ -0,0 +1,623 @@ +.TH LVM FULLREPORT 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvm fullreport \- Display full report +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvm fullreport\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +lvm fullreport produces formatted output about PVs, PV segments, VGs, LVs +and LV segments. The information is all gathered together for each VG +(under a per-VG lock) so it is consistent. Information gathered from +separate calls to \fBvgs\fP, \fBpvs\fP, and \fBlvs\fP can be inconsistent +if information changes between commands. + + +.P +.SH USAGE +.br +.P +. +\fBlvm fullreport\fP +.br +.RS 4 +.ad l +[ \fB-a\fP|\fB--all\fP ] +.ad b +.br +.ad l +[ \fB-o\fP|\fB--options\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-O\fP|\fB--sort\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--aligned\fP ] +.ad b +.br +.ad l +[ \fB--binary\fP ] +.ad b +.br +.ad l +[ \fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP ] +.ad b +.br +.ad l +[ \fB--foreign\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--logonly\fP ] +.ad b +.br +.ad l +[ \fB--nameprefixes\fP ] +.ad b +.br +.ad l +[ \fB--noheadings\fP ] +.ad b +.br +.ad l +[ \fB--nolocking\fP ] +.ad b +.br +.ad l +[ \fB--nosuffix\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--rows\fP ] +.ad b +.br +.ad l +[ \fB--separator\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--shared\fP ] +.ad b +.br +.ad l +[ \fB--trustcache\fP ] +.ad b +.br +.ad l +[ \fB--unbuffered\fP ] +.ad b +.br +.ad l +[ \fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP ] +.ad b +.br +.ad l +[ \fB--unquoted\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--aligned\fP +.br +Use with --separator to align the output columns +.ad b + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +.ad b + +.HP +.ad l +\fB--binary\fP +.br +Use binary values "0" or "1" instead of descriptive literal values +for columns that have exactly two valid values to report (not counting +the "unknown" value which denotes that the value could not be determined). +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--foreign\fP +.br +Report/display foreign VGs that would otherwise be skipped. +See lvmsystemid(7) for more information about foreign VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--logonly\fP +.br +Suppress command report and display only log report. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--nameprefixes\fP +.br +Add an "LVM2_" prefix plus the field name to the output. Useful +with --noheadings to produce a list of field=value pairs that can +be used to set environment variables (for example, in udev rules). +.ad b + +.HP +.ad l +\fB--noheadings\fP +.br +Suppress the headings line that is normally the first line of output. +Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--nolocking\fP +.br +Disable locking. +.ad b + +.HP +.ad l +\fB--nosuffix\fP +.br +Suppress the suffix on output sizes. Use with --units +(except h and H) if processing the output. +.ad b + +.HP +.ad l +\fB-o\fP|\fB--options\fP \fIString\fP +.br +Comma-separated, ordered list of fields to display in columns. +String arg syntax is: [+|-|#]Field1[,Field2 ...] +The prefix \fB+\fP will append the specified fields to the default fields, +\fB-\fP will remove the specified fields from the default fields, and +\fB#\fP will compact specified fields (removing them when empty for all rows.) +Use \fB-o help\fP to view the list of all available fields. +The -o option can be repeated, providing several lists. +These lists are evaluated from left to right. +Use field name \fBlv_all\fP to view all LV fields, +\fBvg_all\fP all VG fields, +\fBpv_all\fP all PV fields, +\fBpvseg_all\fP all PV segment fields, +\fBseg_all\fP all LV segment fields, and +\fBpvseg_all\fP all PV segment columns. +See the lvm.conf report section for more config options. +See lvmreport(7) for more information about reporting. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--rows\fP +.br +Output columns as rows. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB--separator\fP \fIString\fP +.br +String to use to separate each column. Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--shared\fP +.br +Report/display shared VGs that would otherwise be skipped when +lvmlockd is not being used on the host. +See lvmlockd(8) for more information about shared VGs. +.ad b + +.HP +.ad l +\fB-O\fP|\fB--sort\fP \fIString\fP +.br +Comma-separated ordered list of columns to sort by. Replaces the default +selection. Precede any column with \fB-\fP for a reverse sort on that column. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--trustcache\fP +.br +Avoids certain device scanning during command processing. Do not use. +.ad b + +.HP +.ad l +\fB--unbuffered\fP +.br +Produce output immediately without sorting or aligning the columns properly. +.ad b + +.HP +.ad l +\fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP +.br +All sizes are output in these units: +human-(r)eadable with '<' rounding indicator, +(h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, +(g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. +Capitalise to use multiples of 1000 (S.I.) instead of 1024. +Custom units can be specified, e.g. --units 3M. +.ad b + +.HP +.ad l +\fB--unquoted\fP +.br +When used with --nameprefixes, output values in the field=value +pairs are not quoted. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvm-lvpoll.8.des b/man/lvm-lvpoll.8.des deleted file mode 100644 index 35c2522..0000000 --- a/man/lvm-lvpoll.8.des +++ /dev/null @@ -1,4 +0,0 @@ -lvm lvpoll is an internal command used by \fBlvmpolld\fP(8) to monitor and -complete \fBlvconvert\fP(8) and \fBpvmove\fP(8) operations. lvpoll itself -does not initiate these operations and should not normally need to be run -directly. diff --git a/man/lvm-lvpoll.8.end b/man/lvm-lvpoll.8.end deleted file mode 100644 index eddb364..0000000 --- a/man/lvm-lvpoll.8.end +++ /dev/null @@ -1,33 +0,0 @@ -.SH NOTES - -To find the name of the pvmove LV that was created by an original -\fBpvmove /dev/name\fP command, use the command: -.br -\fBlvs -a -S move_pv=/dev/name\fP. - -.SH EXAMPLES - -Continue polling a pvmove operation. -.br -.B lvm lvpoll --polloperation pvmove vg00/pvmove0 - -Abort a pvmove operation. -.br -.B lvm lvpoll --polloperation pvmove --abort vg00/pvmove0 - -Continue polling a mirror conversion. -.br -.B lvm lvpoll --polloperation convert vg00/lvmirror - -Continue mirror repair. -.br -.B lvm lvpoll --polloperation convert vg/damaged_mirror --handlemissingpvs - -Continue snapshot merge. -.br -.B lvm lvpoll --polloperation merge vg/snapshot_old - -Continue thin snapshot merge. -.br -.B lvm lvpoll --polloperation merge_thin vg/thin_snapshot - diff --git a/man/lvm-lvpoll.8_des b/man/lvm-lvpoll.8_des new file mode 100644 index 0000000..35c2522 --- /dev/null +++ b/man/lvm-lvpoll.8_des @@ -0,0 +1,4 @@ +lvm lvpoll is an internal command used by \fBlvmpolld\fP(8) to monitor and +complete \fBlvconvert\fP(8) and \fBpvmove\fP(8) operations. lvpoll itself +does not initiate these operations and should not normally need to be run +directly. diff --git a/man/lvm-lvpoll.8_end b/man/lvm-lvpoll.8_end new file mode 100644 index 0000000..eddb364 --- /dev/null +++ b/man/lvm-lvpoll.8_end @@ -0,0 +1,33 @@ +.SH NOTES + +To find the name of the pvmove LV that was created by an original +\fBpvmove /dev/name\fP command, use the command: +.br +\fBlvs -a -S move_pv=/dev/name\fP. + +.SH EXAMPLES + +Continue polling a pvmove operation. +.br +.B lvm lvpoll --polloperation pvmove vg00/pvmove0 + +Abort a pvmove operation. +.br +.B lvm lvpoll --polloperation pvmove --abort vg00/pvmove0 + +Continue polling a mirror conversion. +.br +.B lvm lvpoll --polloperation convert vg00/lvmirror + +Continue mirror repair. +.br +.B lvm lvpoll --polloperation convert vg/damaged_mirror --handlemissingpvs + +Continue snapshot merge. +.br +.B lvm lvpoll --polloperation merge vg/snapshot_old + +Continue thin snapshot merge. +.br +.B lvm lvpoll --polloperation merge_thin vg/thin_snapshot + diff --git a/man/lvm-lvpoll.8_pregen b/man/lvm-lvpoll.8_pregen new file mode 100644 index 0000000..935123c --- /dev/null +++ b/man/lvm-lvpoll.8_pregen @@ -0,0 +1,373 @@ +.TH LVM LVPOLL 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvm lvpoll \- Continue already initiated poll operation on a logical volume +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvm lvpoll\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +lvm lvpoll is an internal command used by \fBlvmpolld\fP(8) to monitor and +complete \fBlvconvert\fP(8) and \fBpvmove\fP(8) operations. lvpoll itself +does not initiate these operations and should not normally need to be run +directly. + +.P +.SH USAGE +.br +.P +. +\fBlvm lvpoll\fP \fB--polloperation\fP \fBpvmove\fP|\fBconvert\fP|\fBmerge\fP|\fBmerge_thin\fP \fILV\fP ... +.br +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--abort\fP ] +.ad b +.br +.ad l +[ \fB--handlemissingpvs\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--abort\fP +.br +Stop processing a poll operation in lvmpolld. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--handlemissingpvs\fP +.br +Allows a polling operation to continue when PVs are missing, +e.g. for repairs due to faulty devices. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-i\fP|\fB--interval\fP \fINumber\fP +.br +Report progress at regular intervals. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--polloperation\fP \fBpvmove\fP|\fBconvert\fP|\fBmerge\fP|\fBmerge_thin\fP +.br +The command to perform from lvmpolld. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH NOTES + +To find the name of the pvmove LV that was created by an original +\fBpvmove /dev/name\fP command, use the command: +.br +\fBlvs -a -S move_pv=/dev/name\fP. + +.SH EXAMPLES + +Continue polling a pvmove operation. +.br +.B lvm lvpoll --polloperation pvmove vg00/pvmove0 + +Abort a pvmove operation. +.br +.B lvm lvpoll --polloperation pvmove --abort vg00/pvmove0 + +Continue polling a mirror conversion. +.br +.B lvm lvpoll --polloperation convert vg00/lvmirror + +Continue mirror repair. +.br +.B lvm lvpoll --polloperation convert vg/damaged_mirror --handlemissingpvs + +Continue snapshot merge. +.br +.B lvm lvpoll --polloperation merge vg/snapshot_old + +Continue thin snapshot merge. +.br +.B lvm lvpoll --polloperation merge_thin vg/thin_snapshot + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvm.8.in b/man/lvm.8.in deleted file mode 100644 index 1f3247a..0000000 --- a/man/lvm.8.in +++ /dev/null @@ -1,553 +0,0 @@ -.TH LVM 8 "LVM TOOLS #VERSION#" "Sistina Software UK" \" -*- nroff -*- -. -.SH NAME -. -lvm \(em LVM2 tools -. -.SH SYNOPSIS -. -.B lvm -.RI [ command | file ] -. -.SH DESCRIPTION -. -lvm provides the command-line tools for LVM2. A separate -manual page describes each command in detail. -.P -If \fBlvm\fP is invoked with no arguments it presents a readline prompt -(assuming it was compiled with readline support). -LVM commands may be entered interactively at this prompt with -readline facilities including history and command name and option -completion. Refer to \fBreadline\fP(3) for details. -.P -If \fBlvm\fP is invoked with argv[0] set to the name of a specific -LVM command (for example by using a hard or soft link) it acts as -that command. -.P -On invocation, \fBlvm\fP requires that only the standard file descriptors -stdin, stdout and stderr are available. If others are found, they -get closed and messages are issued warning about the leak. -This warning can be suppressed by setting the environment variable -.B LVM_SUPPRESS_FD_WARNINGS\fP. -.P -Where commands take VG or LV names as arguments, the full path name is -optional. An LV called "lvol0" in a VG called "vg0" can be specified -as "vg0/lvol0". Where a list of VGs is required but is left empty, -a list of all VGs will be substituted. Where a list of LVs is required -but a VG is given, a list of all the LVs in that VG will be substituted. -So \fBlvdisplay vg0\fP will display all the LVs in "vg0". -Tags can also be used - see \fB\-\-addtag\fP below. -.P -One advantage of using the built-in shell is that configuration -information gets cached internally between commands. -.P -A file containing a simple script with one command per line -can also be given on the command line. The script can also be -executed directly if the first line is #! followed by the absolute -path of \fBlvm\fP. -.P -Additional hyphens within option names are ignored. For example, -\fB\-\-readonly\fP and \fB\-\-read\-only\fP are both accepted. -. -.SH BUILT-IN COMMANDS -. -The following commands are built into lvm without links -normally being created in the filesystem for them. -.sp -.PD 0 -.TP 14 -.B config -The same as \fBlvmconfig\fP(8) below. -.TP -.B devtypes -Display the recognised built-in block device types. -.TP -.B dumpconfig -The same as \fBlvmconfig\fP(8) below. -.TP -.B formats -Display recognised metadata formats. -.TP -.B fullreport -Report information about PVs, PV segments, VGs, LVs and LV segments, -all at once. -.TP -.B help -Display the help text. -.TP -.B lastlog -Display log report of last command run in LVM shell -if command log reporting is enabled. -.TP -.B lvpoll -Complete lvmpolld operations (Internal command). -.TP -.B pvdata -Not implemented in LVM2. -.TP -.B segtypes -Display recognised Logical Volume segment types. -.TP -.B systemid -Display any system ID currently set on this host. -.TP -.B tags -Display any tags defined on this host. -.TP -.B version -Display version information. -.PD -. -.SH COMMANDS -. -The following commands implement the core LVM functionality. -.sp -.PD 0 -.TP 14 -.B pvchange -Change attributes of a Physical Volume. -.TP -.B pvck -Check Physical Volume metadata. -.TP -.B pvcreate -Initialize a disk or partition for use by LVM. -.TP -.B pvdisplay -Display attributes of a Physical Volume. -.TP -.B pvmove -Move Physical Extents. -.TP -.B pvremove -Remove a Physical Volume. -.TP -.B pvresize -Resize a disk or partition in use by LVM2. -.TP -.B pvs -Report information about Physical Volumes. -.TP -.B pvscan -Scan all disks for Physical Volumes. -.TP -.B vgcfgbackup -Backup Volume Group descriptor area. -.TP -.B vgcfgrestore -Restore Volume Group descriptor area. -.TP -.B vgchange -Change attributes of a Volume Group. -.TP -.B vgck -Check Volume Group metadata. -.TP -.B vgconvert -Convert Volume Group metadata format. -.TP -.B vgcreate -Create a Volume Group. -.TP -.B vgdisplay -Display attributes of Volume Groups. -.TP -.B vgexport -Make volume Groups unknown to the system. -.TP -.B vgextend -Add Physical Volumes to a Volume Group. -.TP -.B vgimport -Make exported Volume Groups known to the system. -.TP -.B vgimportclone -Import and rename duplicated Volume Group (e.g. a hardware snapshot). -.TP -.B vgmerge -Merge two Volume Groups. -.TP -.B vgmknodes -Recreate Volume Group directory and Logical Volume special files -.TP -.B vgreduce -Reduce a Volume Group by removing one or more Physical Volumes. -.TP -.B vgremove -Remove a Volume Group. -.TP -.B vgrename -Rename a Volume Group. -.TP -.B vgs -Report information about Volume Groups. -.TP -.B vgscan -Scan all disks for Volume Groups and rebuild caches. -.TP -.B vgsplit -Split a Volume Group into two, moving any logical -volumes from one Volume Group to another by moving entire Physical -Volumes. -.TP -.B lvchange -Change attributes of a Logical Volume. -.TP -.B lvconvert -Convert a Logical Volume from linear to mirror or snapshot. -.TP -.B lvcreate -Create a Logical Volume in an existing Volume Group. -.TP -.B lvdisplay -Display attributes of a Logical Volume. -.TP -.B lvextend -Extend the size of a Logical Volume. -.TP -.B lvmchange -Change attributes of the Logical Volume Manager. -.TP -.B lvmconfig -Display the configuration information after -loading \fBlvm.conf\fP(5) and any other configuration files. -.TP -.B lvmdiskscan -Scan for all devices visible to LVM2. -.TP -.B lvmdump -Create lvm2 information dumps for diagnostic purposes. -.TP -.B lvreduce -Reduce the size of a Logical Volume. -.TP -.B lvremove -Remove a Logical Volume. -.TP -.B lvrename -Rename a Logical Volume. -.TP -.B lvresize -Resize a Logical Volume. -.TP -.B lvs -Report information about Logical Volumes. -.TP -.B lvscan -Scan (all disks) for Logical Volumes. -.PD -.P -The following commands are not implemented in LVM2 but might be -in the future: -.BR lvmsadc ", " lvmsar ", " pvdata . -. -.SH VALID NAMES -. -The valid characters for VG and LV names are: -.BR a - z -.BR A - Z -.BR 0 - 9 -.BR "+ _ . -" -.P -VG names cannot begin with a hyphen. -The name of a new LV also cannot begin with a hyphen. However, if the -configuration setting \fBmetadata/record_lvs_history\fP is enabled then an LV -name with a hyphen as a prefix indicates that, although the LV was -removed, it is still being tracked because it forms part of the history of at -least one LV that is still present. This helps to record the ancestry of -thin snapshots even after some links in the chain have been removed. -A reference to the historical LV 'lvol1' in VG 'vg00' would be 'vg00/-lvol1' -or just '-lvol1' if the VG is already set. (The latter form must be preceded -by '--' to terminate command line option processing before reaching this -argument.) -.P -There are also various reserved names that are used internally by lvm that can -not be used as LV or VG names. A VG cannot be called anything that exists in -\fI/dev/\fP@the time of creation, nor can it be called '.' or '..'. -An LV cannot be called '.', '..', 'snapshot' or 'pvmove'. -The LV name may also not contain any of the following strings: -\fR'_cdata', '_cmeta', '_corig', '_mlog', '_mimage', '_pmspare', -\fR'_rimage', '_rmeta', '_tdata', '_tmeta' or '_vorigin'. -A directory bearing the name of each Volume Group is created under -\fI/dev\fP when any of its Logical Volumes are activated. -Each active Logical Volume is accessible from this directory as a symbolic -link leading to a device node. -Links or nodes in \fI/dev/mapper\fP are intended only for internal use and -the precise format and escaping might change between releases and distributions. -Other software and scripts should use the -\fI/dev/VolumeGroupName/LogicalVolumeName\fP format to reduce the chance of needing -amendment when the software is updated. Should you need to process the node -names in /dev/mapper, you may use \fBdmsetup splitname\fP to separate out the -original VG, LV and internal layer names. -.P -. -.SH UNIQUE NAMES -. - -VG names should be unique. vgcreate will produce an error if the -specified VG name matches an existing VG name. However, there are cases -where different VGs with the same name can appear to LVM, e.g. after -moving disks or changing filters. - -When VGs with the same name exist, commands operating on all VGs will -include all of the VGs with the same name. If the ambiguous VG name is -specified on the command line, the command will produce an error. The -error states that multiple VGs exist with the specified name. To process -one of the VGs specifically, the --select option should be used with the -UUID of the intended VG: '--select vg_uuid='. - -An exception is if all but one of the VGs with the shared name is foreign -(see -.BR lvmsystemid (7).) -In this case, the one VG that is not foreign is assumed to be the intended -VG and is processed. -.P -LV names are unique within a VG. The name of an historical LV cannot be -reused until the historical LV has itself been removed or renamed. - -. -.SH ALLOCATION -. -When an operation needs to allocate Physical Extents for one or more -Logical Volumes, the tools proceed as follows: - -First of all, they generate the complete set of unallocated Physical Extents -in the Volume Group. If any ranges of Physical Extents are supplied at -the end of the command line, only unallocated Physical Extents within -those ranges on the specified Physical Volumes are considered. - -Then they try each allocation policy in turn, starting with the strictest -policy (\fBcontiguous\fP) and ending with the allocation policy specified -using \fB\-\-alloc\fP or set as the default for the particular Logical -Volume or Volume Group concerned. For each policy, working from the -lowest-numbered Logical Extent of the empty Logical Volume space that -needs to be filled, they allocate as much space as possible according to -the restrictions imposed by the policy. If more space is needed, -they move on to the next policy. - -The restrictions are as follows: - -\fBContiguous\fP requires that the physical location of any Logical -Extent that is not the first Logical Extent of a Logical Volume is -adjacent to the physical location of the Logical Extent immediately -preceding it. - -\fBCling\fP requires that the Physical Volume used for any Logical -Extent to be added to an existing Logical Volume is already in use by at -least one Logical Extent earlier in that Logical Volume. If the -configuration parameter \fBallocation/cling_tag_list\fP is defined, then two -Physical Volumes are considered to match if any of the listed tags is -present on both Physical Volumes. This allows groups of Physical -Volumes with similar properties (such as their physical location) to be -tagged and treated as equivalent for allocation purposes. - -When a Logical Volume is striped or mirrored, the above restrictions are -applied independently to each stripe or mirror image (leg) that needs -space. - -\fBNormal\fP will not choose a Physical Extent that shares the same Physical -Volume as a Logical Extent already allocated to a parallel Logical -Volume (i.e. a different stripe or mirror image/leg) at the same offset -within that parallel Logical Volume. - -When allocating a mirror log at the same time as Logical Volumes to hold -the mirror data, Normal will first try to select different Physical -Volumes for the log and the data. If that's not possible and the -.B allocation/mirror_logs_require_separate_pvs -configuration parameter is set to 0, it will then allow the log -to share Physical Volume(s) with part of the data. - -When allocating thin pool metadata, similar considerations to those of a -mirror log in the last paragraph apply based on the value of the -.B allocation/thin_pool_metadata_require_separate_pvs -configuration parameter. - -If you rely upon any layout behaviour beyond that documented here, be -aware that it might change in future versions of the code. - -For example, if you supply on the command line two empty Physical -Volumes that have an identical number of free Physical Extents available for -allocation, the current code considers using each of them in the order -they are listed, but there is no guarantee that future releases will -maintain that property. If it is important to obtain a specific layout -for a particular Logical Volume, then you should build it up through a -sequence of \fBlvcreate\fP(8) and \fBlvconvert\fP(8) steps such that the -restrictions described above applied to each step leave the tools no -discretion over the layout. - -To view the way the allocation process currently works in any specific -case, read the debug logging output, for example by adding \fB\-vvvv\fP to -a command. -. -.SH LOGICAL VOLUME TYPES -. -Some logical volume types are simple to create and can be done with a -single \fBlvcreate\fP(8) command. The linear and striped logical -volume types are an example of this. Other logical volume types may -require more than one command to create. The cache (\fBlvmcache\fP(7)) -and thin provisioning (\fBlvmthin\fP(7)) types are examples of this. -. -.SH DIAGNOSTICS -. -All tools return a status code of zero on success or non-zero on failure. -The non-zero codes distinguish only between the broad categories of -unrecognised commands, problems processing the command line arguments -and any other failures. As LVM remains under active development, the -code used in a specific case occasionally changes between releases. -Message text may also change. -. -.SH ENVIRONMENT VARIABLES -. -.TP -.B HOME -Directory containing \fI.lvm_history\fP if the internal readline -shell is invoked. -.TP -.B LVM_OUT_FD -File descriptor to use for common output from LVM commands. -.TP -.B LVM_ERR_FD -File descriptor to use for error output from LVM commands. -.TP -.B LVM_REPORT_FD -File descriptor to use for report output from LVM commands. -.TP -.B LVM_COMMAND_PROFILE -Name of default command profile to use for LVM commands. This profile -is overriden by direct use of \fB\-\-commandprofile\fP command line option. -.TP -.B LVM_RUN_BY_DMEVENTD -This variable is normally set by dmeventd plugin to inform lvm2 command -it is running from dmeventd plugin so lvm2 takes some extra action -to avoid comunication and deadlocks with dmeventd. -.TP -.B LVM_SYSTEM_DIR -Directory containing \fBlvm.conf\fP(5) and other LVM system files. -Defaults to "\fI#DEFAULT_SYS_DIR#\fP". -.TP -.B LVM_SUPPRESS_FD_WARNINGS -Suppress warnings about unexpected file descriptors passed into LVM. -.TP -.B LVM_VG_NAME -The Volume Group name that is assumed for -any reference to a Logical Volume that doesn't specify a path. -Not set by default. -.TP -.B LVM_LVMETAD_PIDFILE -Path to the file that stores the lvmetad process ID. -.TP -.B LVM_LVMETAD_SOCKET -Path to the socket used to communicate with lvmetad. -.TP -.B LVM_LVMPOLLD_PIDFILE -Path to the file that stores the lvmpolld process ID. -.TP -.B LVM_LVMPOLLD_SOCKET -Path to the socket used to communicate with lvmpolld.. -.TP -.B LVM_LOG_FILE_EPOCH -A string of up to 32 letters appended to the log filename and -followed by the process ID and a startup timestamp using -this format string "_%s_%d_%llu". When set, each process logs to a -separate file. -.TP -.B LVM_LOG_FILE_MAX_LINES -If more than this number of lines are sent to the log file, the command gets -aborted. Automated tests use this to terminate looping commands. -.TP -.B LVM_EXPECTED_EXIT_STATUS -The status anticipated when the process exits. Use ">N" to match any -status greater than N. If the actual exit status matches and a log -file got produced, it is deleted. -.B LVM_LOG_FILE_EPOCH -and -.B LVM_EXPECTED_EXIT_STATUS -together allow automated test scripts to discard uninteresting log data. -.TP -.B LVM_SUPPRESS_LOCKING_FAILURE_MESSAGES -Used to suppress warning messages when the configured locking is known -to be unavailable. -.TP -.B DM_ABORT_ON_INTERNAL_ERRORS -Abort processing if the code detects a non-fatal internal error. -.TP -.B DM_DISABLE_UDEV -Avoid interaction with udev. LVM will manage the relevant nodes in /dev -directly. -. -.SH FILES -. -.I #DEFAULT_SYS_DIR#/lvm.conf -.br -.I $HOME/.lvm_history -. -.SH SEE ALSO -. -.nh -.BR lvm (8) -.BR lvm.conf (5) -.BR lvmconfig (8) - -.BR pvchange (8) -.BR pvck (8) -.BR pvcreate (8) -.BR pvdisplay (8) -.BR pvmove (8) -.BR pvremove (8) -.BR pvresize (8) -.BR pvs (8) -.BR pvscan (8) - -.BR vgcfgbackup (8) -.BR vgcfgrestore (8) -.BR vgchange (8) -.BR vgck (8) -.BR vgcreate (8) -.BR vgconvert (8) -.BR vgdisplay (8) -.BR vgexport (8) -.BR vgextend (8) -.BR vgimport (8) -.BR vgimportclone (8) -.BR vgmerge (8) -.BR vgmknodes (8) -.BR vgreduce (8) -.BR vgremove (8) -.BR vgrename (8) -.BR vgs (8) -.BR vgscan (8) -.BR vgsplit (8) - -.BR lvcreate (8) -.BR lvchange (8) -.BR lvconvert (8) -.BR lvdisplay (8) -.BR lvextend (8) -.BR lvreduce (8) -.BR lvremove (8) -.BR lvrename (8) -.BR lvresize (8) -.BR lvs (8) -.BR lvscan (8) - -.BR lvm2-activation-generator (8) -.BR blkdeactivate (8) -.BR lvmdump (8) - -.BR dmeventd (8) -.BR lvmetad (8) -.BR lvmpolld (8) -.BR lvmlockd (8) -.BR lvmlockctl (8) -.BR clvmd (8) -.BR cmirrord (8) -.BR lvmdbusd (8) - -.BR lvmsystemid (7) -.BR lvmreport (7) -.BR lvmraid (7) -.BR lvmthin (7) -.BR lvmcache (7) - -.BR dmsetup (8), -.BR readline (3) diff --git a/man/lvm.8_main b/man/lvm.8_main new file mode 100644 index 0000000..1f3247a --- /dev/null +++ b/man/lvm.8_main @@ -0,0 +1,553 @@ +.TH LVM 8 "LVM TOOLS #VERSION#" "Sistina Software UK" \" -*- nroff -*- +. +.SH NAME +. +lvm \(em LVM2 tools +. +.SH SYNOPSIS +. +.B lvm +.RI [ command | file ] +. +.SH DESCRIPTION +. +lvm provides the command-line tools for LVM2. A separate +manual page describes each command in detail. +.P +If \fBlvm\fP is invoked with no arguments it presents a readline prompt +(assuming it was compiled with readline support). +LVM commands may be entered interactively at this prompt with +readline facilities including history and command name and option +completion. Refer to \fBreadline\fP(3) for details. +.P +If \fBlvm\fP is invoked with argv[0] set to the name of a specific +LVM command (for example by using a hard or soft link) it acts as +that command. +.P +On invocation, \fBlvm\fP requires that only the standard file descriptors +stdin, stdout and stderr are available. If others are found, they +get closed and messages are issued warning about the leak. +This warning can be suppressed by setting the environment variable +.B LVM_SUPPRESS_FD_WARNINGS\fP. +.P +Where commands take VG or LV names as arguments, the full path name is +optional. An LV called "lvol0" in a VG called "vg0" can be specified +as "vg0/lvol0". Where a list of VGs is required but is left empty, +a list of all VGs will be substituted. Where a list of LVs is required +but a VG is given, a list of all the LVs in that VG will be substituted. +So \fBlvdisplay vg0\fP will display all the LVs in "vg0". +Tags can also be used - see \fB\-\-addtag\fP below. +.P +One advantage of using the built-in shell is that configuration +information gets cached internally between commands. +.P +A file containing a simple script with one command per line +can also be given on the command line. The script can also be +executed directly if the first line is #! followed by the absolute +path of \fBlvm\fP. +.P +Additional hyphens within option names are ignored. For example, +\fB\-\-readonly\fP and \fB\-\-read\-only\fP are both accepted. +. +.SH BUILT-IN COMMANDS +. +The following commands are built into lvm without links +normally being created in the filesystem for them. +.sp +.PD 0 +.TP 14 +.B config +The same as \fBlvmconfig\fP(8) below. +.TP +.B devtypes +Display the recognised built-in block device types. +.TP +.B dumpconfig +The same as \fBlvmconfig\fP(8) below. +.TP +.B formats +Display recognised metadata formats. +.TP +.B fullreport +Report information about PVs, PV segments, VGs, LVs and LV segments, +all at once. +.TP +.B help +Display the help text. +.TP +.B lastlog +Display log report of last command run in LVM shell +if command log reporting is enabled. +.TP +.B lvpoll +Complete lvmpolld operations (Internal command). +.TP +.B pvdata +Not implemented in LVM2. +.TP +.B segtypes +Display recognised Logical Volume segment types. +.TP +.B systemid +Display any system ID currently set on this host. +.TP +.B tags +Display any tags defined on this host. +.TP +.B version +Display version information. +.PD +. +.SH COMMANDS +. +The following commands implement the core LVM functionality. +.sp +.PD 0 +.TP 14 +.B pvchange +Change attributes of a Physical Volume. +.TP +.B pvck +Check Physical Volume metadata. +.TP +.B pvcreate +Initialize a disk or partition for use by LVM. +.TP +.B pvdisplay +Display attributes of a Physical Volume. +.TP +.B pvmove +Move Physical Extents. +.TP +.B pvremove +Remove a Physical Volume. +.TP +.B pvresize +Resize a disk or partition in use by LVM2. +.TP +.B pvs +Report information about Physical Volumes. +.TP +.B pvscan +Scan all disks for Physical Volumes. +.TP +.B vgcfgbackup +Backup Volume Group descriptor area. +.TP +.B vgcfgrestore +Restore Volume Group descriptor area. +.TP +.B vgchange +Change attributes of a Volume Group. +.TP +.B vgck +Check Volume Group metadata. +.TP +.B vgconvert +Convert Volume Group metadata format. +.TP +.B vgcreate +Create a Volume Group. +.TP +.B vgdisplay +Display attributes of Volume Groups. +.TP +.B vgexport +Make volume Groups unknown to the system. +.TP +.B vgextend +Add Physical Volumes to a Volume Group. +.TP +.B vgimport +Make exported Volume Groups known to the system. +.TP +.B vgimportclone +Import and rename duplicated Volume Group (e.g. a hardware snapshot). +.TP +.B vgmerge +Merge two Volume Groups. +.TP +.B vgmknodes +Recreate Volume Group directory and Logical Volume special files +.TP +.B vgreduce +Reduce a Volume Group by removing one or more Physical Volumes. +.TP +.B vgremove +Remove a Volume Group. +.TP +.B vgrename +Rename a Volume Group. +.TP +.B vgs +Report information about Volume Groups. +.TP +.B vgscan +Scan all disks for Volume Groups and rebuild caches. +.TP +.B vgsplit +Split a Volume Group into two, moving any logical +volumes from one Volume Group to another by moving entire Physical +Volumes. +.TP +.B lvchange +Change attributes of a Logical Volume. +.TP +.B lvconvert +Convert a Logical Volume from linear to mirror or snapshot. +.TP +.B lvcreate +Create a Logical Volume in an existing Volume Group. +.TP +.B lvdisplay +Display attributes of a Logical Volume. +.TP +.B lvextend +Extend the size of a Logical Volume. +.TP +.B lvmchange +Change attributes of the Logical Volume Manager. +.TP +.B lvmconfig +Display the configuration information after +loading \fBlvm.conf\fP(5) and any other configuration files. +.TP +.B lvmdiskscan +Scan for all devices visible to LVM2. +.TP +.B lvmdump +Create lvm2 information dumps for diagnostic purposes. +.TP +.B lvreduce +Reduce the size of a Logical Volume. +.TP +.B lvremove +Remove a Logical Volume. +.TP +.B lvrename +Rename a Logical Volume. +.TP +.B lvresize +Resize a Logical Volume. +.TP +.B lvs +Report information about Logical Volumes. +.TP +.B lvscan +Scan (all disks) for Logical Volumes. +.PD +.P +The following commands are not implemented in LVM2 but might be +in the future: +.BR lvmsadc ", " lvmsar ", " pvdata . +. +.SH VALID NAMES +. +The valid characters for VG and LV names are: +.BR a - z +.BR A - Z +.BR 0 - 9 +.BR "+ _ . -" +.P +VG names cannot begin with a hyphen. +The name of a new LV also cannot begin with a hyphen. However, if the +configuration setting \fBmetadata/record_lvs_history\fP is enabled then an LV +name with a hyphen as a prefix indicates that, although the LV was +removed, it is still being tracked because it forms part of the history of at +least one LV that is still present. This helps to record the ancestry of +thin snapshots even after some links in the chain have been removed. +A reference to the historical LV 'lvol1' in VG 'vg00' would be 'vg00/-lvol1' +or just '-lvol1' if the VG is already set. (The latter form must be preceded +by '--' to terminate command line option processing before reaching this +argument.) +.P +There are also various reserved names that are used internally by lvm that can +not be used as LV or VG names. A VG cannot be called anything that exists in +\fI/dev/\fP at the time of creation, nor can it be called '.' or '..'. +An LV cannot be called '.', '..', 'snapshot' or 'pvmove'. +The LV name may also not contain any of the following strings: +\fR'_cdata', '_cmeta', '_corig', '_mlog', '_mimage', '_pmspare', +\fR'_rimage', '_rmeta', '_tdata', '_tmeta' or '_vorigin'. +A directory bearing the name of each Volume Group is created under +\fI/dev\fP when any of its Logical Volumes are activated. +Each active Logical Volume is accessible from this directory as a symbolic +link leading to a device node. +Links or nodes in \fI/dev/mapper\fP are intended only for internal use and +the precise format and escaping might change between releases and distributions. +Other software and scripts should use the +\fI/dev/VolumeGroupName/LogicalVolumeName\fP format to reduce the chance of needing +amendment when the software is updated. Should you need to process the node +names in /dev/mapper, you may use \fBdmsetup splitname\fP to separate out the +original VG, LV and internal layer names. +.P +. +.SH UNIQUE NAMES +. + +VG names should be unique. vgcreate will produce an error if the +specified VG name matches an existing VG name. However, there are cases +where different VGs with the same name can appear to LVM, e.g. after +moving disks or changing filters. + +When VGs with the same name exist, commands operating on all VGs will +include all of the VGs with the same name. If the ambiguous VG name is +specified on the command line, the command will produce an error. The +error states that multiple VGs exist with the specified name. To process +one of the VGs specifically, the --select option should be used with the +UUID of the intended VG: '--select vg_uuid='. + +An exception is if all but one of the VGs with the shared name is foreign +(see +.BR lvmsystemid (7).) +In this case, the one VG that is not foreign is assumed to be the intended +VG and is processed. +.P +LV names are unique within a VG. The name of an historical LV cannot be +reused until the historical LV has itself been removed or renamed. + +. +.SH ALLOCATION +. +When an operation needs to allocate Physical Extents for one or more +Logical Volumes, the tools proceed as follows: + +First of all, they generate the complete set of unallocated Physical Extents +in the Volume Group. If any ranges of Physical Extents are supplied at +the end of the command line, only unallocated Physical Extents within +those ranges on the specified Physical Volumes are considered. + +Then they try each allocation policy in turn, starting with the strictest +policy (\fBcontiguous\fP) and ending with the allocation policy specified +using \fB\-\-alloc\fP or set as the default for the particular Logical +Volume or Volume Group concerned. For each policy, working from the +lowest-numbered Logical Extent of the empty Logical Volume space that +needs to be filled, they allocate as much space as possible according to +the restrictions imposed by the policy. If more space is needed, +they move on to the next policy. + +The restrictions are as follows: + +\fBContiguous\fP requires that the physical location of any Logical +Extent that is not the first Logical Extent of a Logical Volume is +adjacent to the physical location of the Logical Extent immediately +preceding it. + +\fBCling\fP requires that the Physical Volume used for any Logical +Extent to be added to an existing Logical Volume is already in use by at +least one Logical Extent earlier in that Logical Volume. If the +configuration parameter \fBallocation/cling_tag_list\fP is defined, then two +Physical Volumes are considered to match if any of the listed tags is +present on both Physical Volumes. This allows groups of Physical +Volumes with similar properties (such as their physical location) to be +tagged and treated as equivalent for allocation purposes. + +When a Logical Volume is striped or mirrored, the above restrictions are +applied independently to each stripe or mirror image (leg) that needs +space. + +\fBNormal\fP will not choose a Physical Extent that shares the same Physical +Volume as a Logical Extent already allocated to a parallel Logical +Volume (i.e. a different stripe or mirror image/leg) at the same offset +within that parallel Logical Volume. + +When allocating a mirror log at the same time as Logical Volumes to hold +the mirror data, Normal will first try to select different Physical +Volumes for the log and the data. If that's not possible and the +.B allocation/mirror_logs_require_separate_pvs +configuration parameter is set to 0, it will then allow the log +to share Physical Volume(s) with part of the data. + +When allocating thin pool metadata, similar considerations to those of a +mirror log in the last paragraph apply based on the value of the +.B allocation/thin_pool_metadata_require_separate_pvs +configuration parameter. + +If you rely upon any layout behaviour beyond that documented here, be +aware that it might change in future versions of the code. + +For example, if you supply on the command line two empty Physical +Volumes that have an identical number of free Physical Extents available for +allocation, the current code considers using each of them in the order +they are listed, but there is no guarantee that future releases will +maintain that property. If it is important to obtain a specific layout +for a particular Logical Volume, then you should build it up through a +sequence of \fBlvcreate\fP(8) and \fBlvconvert\fP(8) steps such that the +restrictions described above applied to each step leave the tools no +discretion over the layout. + +To view the way the allocation process currently works in any specific +case, read the debug logging output, for example by adding \fB\-vvvv\fP to +a command. +. +.SH LOGICAL VOLUME TYPES +. +Some logical volume types are simple to create and can be done with a +single \fBlvcreate\fP(8) command. The linear and striped logical +volume types are an example of this. Other logical volume types may +require more than one command to create. The cache (\fBlvmcache\fP(7)) +and thin provisioning (\fBlvmthin\fP(7)) types are examples of this. +. +.SH DIAGNOSTICS +. +All tools return a status code of zero on success or non-zero on failure. +The non-zero codes distinguish only between the broad categories of +unrecognised commands, problems processing the command line arguments +and any other failures. As LVM remains under active development, the +code used in a specific case occasionally changes between releases. +Message text may also change. +. +.SH ENVIRONMENT VARIABLES +. +.TP +.B HOME +Directory containing \fI.lvm_history\fP if the internal readline +shell is invoked. +.TP +.B LVM_OUT_FD +File descriptor to use for common output from LVM commands. +.TP +.B LVM_ERR_FD +File descriptor to use for error output from LVM commands. +.TP +.B LVM_REPORT_FD +File descriptor to use for report output from LVM commands. +.TP +.B LVM_COMMAND_PROFILE +Name of default command profile to use for LVM commands. This profile +is overriden by direct use of \fB\-\-commandprofile\fP command line option. +.TP +.B LVM_RUN_BY_DMEVENTD +This variable is normally set by dmeventd plugin to inform lvm2 command +it is running from dmeventd plugin so lvm2 takes some extra action +to avoid comunication and deadlocks with dmeventd. +.TP +.B LVM_SYSTEM_DIR +Directory containing \fBlvm.conf\fP(5) and other LVM system files. +Defaults to "\fI#DEFAULT_SYS_DIR#\fP". +.TP +.B LVM_SUPPRESS_FD_WARNINGS +Suppress warnings about unexpected file descriptors passed into LVM. +.TP +.B LVM_VG_NAME +The Volume Group name that is assumed for +any reference to a Logical Volume that doesn't specify a path. +Not set by default. +.TP +.B LVM_LVMETAD_PIDFILE +Path to the file that stores the lvmetad process ID. +.TP +.B LVM_LVMETAD_SOCKET +Path to the socket used to communicate with lvmetad. +.TP +.B LVM_LVMPOLLD_PIDFILE +Path to the file that stores the lvmpolld process ID. +.TP +.B LVM_LVMPOLLD_SOCKET +Path to the socket used to communicate with lvmpolld.. +.TP +.B LVM_LOG_FILE_EPOCH +A string of up to 32 letters appended to the log filename and +followed by the process ID and a startup timestamp using +this format string "_%s_%d_%llu". When set, each process logs to a +separate file. +.TP +.B LVM_LOG_FILE_MAX_LINES +If more than this number of lines are sent to the log file, the command gets +aborted. Automated tests use this to terminate looping commands. +.TP +.B LVM_EXPECTED_EXIT_STATUS +The status anticipated when the process exits. Use ">N" to match any +status greater than N. If the actual exit status matches and a log +file got produced, it is deleted. +.B LVM_LOG_FILE_EPOCH +and +.B LVM_EXPECTED_EXIT_STATUS +together allow automated test scripts to discard uninteresting log data. +.TP +.B LVM_SUPPRESS_LOCKING_FAILURE_MESSAGES +Used to suppress warning messages when the configured locking is known +to be unavailable. +.TP +.B DM_ABORT_ON_INTERNAL_ERRORS +Abort processing if the code detects a non-fatal internal error. +.TP +.B DM_DISABLE_UDEV +Avoid interaction with udev. LVM will manage the relevant nodes in /dev +directly. +. +.SH FILES +. +.I #DEFAULT_SYS_DIR#/lvm.conf +.br +.I $HOME/.lvm_history +. +.SH SEE ALSO +. +.nh +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + +.BR dmsetup (8), +.BR readline (3) diff --git a/man/lvm.conf.5.in b/man/lvm.conf.5.in deleted file mode 100644 index ae884be..0000000 --- a/man/lvm.conf.5.in +++ /dev/null @@ -1,213 +0,0 @@ -.TH LVM.CONF 5 "LVM TOOLS #VERSION#" "Sistina Software UK" \" -*- nroff -*- -.SH NAME -lvm.conf \(em Configuration file for LVM2 -.SH SYNOPSIS -.B #DEFAULT_SYS_DIR#/lvm.conf -.SH DESCRIPTION -\fBlvm.conf\fP is loaded during the initialisation phase of -\fBlvm\fP(8). This file can in turn lead to other files -being loaded - settings read in later override earlier -settings. File timestamps are checked between commands and if -any have changed, all the files are reloaded. - -The settings defined in lvm.conf can be overridden by any -of these extended configuration methods: -.TP -.B direct config override on command line -The \fB\-\-config ConfigurationString\fP command line option takes the -ConfigurationString as direct string representation of the configuration -to override the existing configuration. The ConfigurationString is of -exactly the same format as used in any LVM configuration file. - -.TP -.B profile config -.br -A profile is a set of selected customizable configuration settings -that are aimed to achieve a certain characteristics in various -environments or uses. It's used to override existing configuration. -Normally, the name of the profile should reflect that environment or use. - -There are two groups of profiles recognised: \fBcommand profiles\fP and -\fBmetadata profiles\fP. - -The \fBcommand profile\fP is used to override selected configuration -settings at global LVM command level - it is applied at the very beginning -of LVM command execution and it is used throughout the whole time of LVM -command execution. The command profile is applied by using the -\fB\-\-commandprofile ProfileName\fP command line option that is recognised by -all LVM2 commands. - -The \fBmetadata profile\fP is used to override selected configuration -settings at Volume Group/Logical Volume level - it is applied independently -for each Volume Group/Logical Volume that is being processed. As such, -each Volume Group/Logical Volume can store the profile name used -in its metadata so next time the Volume Group/Logical Volume is -processed, the profile is applied automatically. If Volume Group and -any of its Logical Volumes have different profiles defined, the profile -defined for the Logical Volume is preferred. The metadata profile can be -attached/detached by using the \fBlvchange\fP and \fBvgchange\fP commands -and their \fB\-\-metadataprofile ProfileName\fP and -\fB\-\-detachprofile\fP options or the \fB\-\-metadataprofile\fP -option during creation when using \fBvgcreate\fP or \fBlvcreate\fP command. -The \fBvgs\fP and \fBlvs\fP reporting commands provide \fB-o vg_profile\fP -and \fB-o lv_profile\fP output options to show the metadata profile -currently attached to a Volume Group or a Logical Volume. - -The set of options allowed for command profiles is mutually exclusive -when compared to the set of options allowed for metadata profiles. The -settings that belong to either of these two sets can't be mixed together -and LVM tools will reject such profiles. - -LVM itself provides a few predefined configuration profiles. -Users are allowed to add more profiles with different values if needed. -For this purpose, there's the \fBcommand_profile_template.profile\fP -(for command profiles) and \fBmetadata_profile_template.profile\fP -(for metadata profiles) which contain all settings that are customizable -by profiles of certain type. Users are encouraged to copy these template -profiles and edit them as needed. Alternatively, the -\fBlvmconfig \-\-file \-\-type profilable-command
\fP -or \fBlvmconfig \-\-file \-\-type profilable-metadata
\fP -can be used to generate a configuration with profilable settings in either -of the type for given section and save it to new ProfileName.profile -(if the section is not specified, all profilable settings are reported). - -The profiles are stored in #DEFAULT_PROFILE_DIR# directory by default. -This location can be changed by using the \fBconfig/profile_dir\fP setting. -Each profile configuration is stored in \fBProfileName.profile\fP file -in the profile directory. When referencing the profile, the \fB.profile\fP -suffix is left out. - -.TP -.B tag config -.br -See \fBtags\fP configuration setting description below. - -.LP -When several configuration methods are used at the same time -and when LVM looks for the value of a particular setting, it traverses -this \fBconfig cascade\fP from left to right: - -\fBdirect config override on command line\fP -> \fBcommand profile config\fP -> \fBmetadata profile config\fP -> \fBtag config\fP -> \fBlvmlocal.conf\fB -> \fBlvm.conf\fP - -No part of this cascade is compulsory. If there's no setting value found at -the end of the cascade, a default value is used for that setting. -Use \fBlvmconfig\fP to check what settings are in use and what -the default values are. -.SH SYNTAX -.LP -This section describes the configuration file syntax. -.LP -Whitespace is not significant unless it is within quotes. -This provides a wide choice of acceptable indentation styles. -Comments begin with # and continue to the end of the line. -They are treated as whitespace. -.LP -Here is an informal grammar: -.TP -.BR file " = " value * -.br -A configuration file consists of a set of values. -.TP -.BR value " = " section " | " assignment -.br -A value can either be a new section, or an assignment. -.TP -.BR section " = " identifier " '" { "' " value "* '" } ' -.br -A section groups associated values together. If the same section is -encountered multiple times, the contents of all instances are concatenated -together in the order of appearance. -.br -It is denoted by a name and delimited by curly brackets. -.br -e.g. backup { -.br - ... -.br - } -.TP -.BR assignment " = " identifier " '" = "' ( " array " | " type " )" -.br -An assignment associates a type with an identifier. If the identifier contains -forward slashes, those are interpreted as path delimiters. The statement -\fBsection/key = value\fP is equivalent to \fBsection { key = value }\fP. If -multiple instances of the same key are encountered, only the last value is used -(and a warning is issued). -.br -e.g. \fBlevel = 7\fP -.br -.TP -.BR array " = '" [ "' ( " type " '" , "')* " type " '" ] "' | '" [ "' '" ] ' -.br -Inhomogeneous arrays are supported. -.br -Elements must be separated by commas. -.br -An empty array is acceptable. -.TP -.BR type " = " integer " | " float " | " string -.BR integer " = [0-9]*" -.br -.BR float " = [0-9]*'" . '[0-9]* -.br -.B string \fR= '\fB"\fR'.*'\fB"\fR' -.IP -Strings with spaces must be enclosed in double quotes, single words that start -with a letter can be left unquoted. - -.SH SETTINGS - -The -.B lvmconfig -command prints the LVM configuration settings in various ways. -See the man page -.BR lvmconfig (8). - -Command to print a list of all possible config settings, with their -default values: -.br -.B lvmconfig \-\-type default - -Command to print a list of all possible config settings, with their -default values, and a full description of each as a comment: -.br -.B lvmconfig \-\-type default --withcomments - -Command to print a list of all possible config settings, with their -current values (configured, non-default values are shown): -.br -.B lvmconfig \-\-type current - -Command to print all config settings that have been configured with a -different value than the default (configured, non-default values are -shown): -.br -.B lvmconfig \-\-type diff - -Command to print a single config setting, with its default value, -and a full description, where "Section" refers to the config section, -e.g. global, and "Setting" refers to the name of the specific setting, -e.g. umask: -.br -.B lvmconfig \-\-type default --withcomments Section/Setting - - -.SH FILES -.I #DEFAULT_SYS_DIR#/lvm.conf -.br -.I #DEFAULT_SYS_DIR#/lvmlocal.conf -.br -.I #DEFAULT_ARCHIVE_DIR# -.br -.I #DEFAULT_BACKUP_DIR# -.br -.I #DEFAULT_CACHE_DIR#/.cache -.br -.I #DEFAULT_LOCK_DIR# -.br -.I #DEFAULT_PROFILE_DIR# - -.SH SEE ALSO -.BR lvm (8) -.BR lvmconfig (8) - diff --git a/man/lvm.conf.5_main b/man/lvm.conf.5_main new file mode 100644 index 0000000..ae884be --- /dev/null +++ b/man/lvm.conf.5_main @@ -0,0 +1,213 @@ +.TH LVM.CONF 5 "LVM TOOLS #VERSION#" "Sistina Software UK" \" -*- nroff -*- +.SH NAME +lvm.conf \(em Configuration file for LVM2 +.SH SYNOPSIS +.B #DEFAULT_SYS_DIR#/lvm.conf +.SH DESCRIPTION +\fBlvm.conf\fP is loaded during the initialisation phase of +\fBlvm\fP(8). This file can in turn lead to other files +being loaded - settings read in later override earlier +settings. File timestamps are checked between commands and if +any have changed, all the files are reloaded. + +The settings defined in lvm.conf can be overridden by any +of these extended configuration methods: +.TP +.B direct config override on command line +The \fB\-\-config ConfigurationString\fP command line option takes the +ConfigurationString as direct string representation of the configuration +to override the existing configuration. The ConfigurationString is of +exactly the same format as used in any LVM configuration file. + +.TP +.B profile config +.br +A profile is a set of selected customizable configuration settings +that are aimed to achieve a certain characteristics in various +environments or uses. It's used to override existing configuration. +Normally, the name of the profile should reflect that environment or use. + +There are two groups of profiles recognised: \fBcommand profiles\fP and +\fBmetadata profiles\fP. + +The \fBcommand profile\fP is used to override selected configuration +settings at global LVM command level - it is applied at the very beginning +of LVM command execution and it is used throughout the whole time of LVM +command execution. The command profile is applied by using the +\fB\-\-commandprofile ProfileName\fP command line option that is recognised by +all LVM2 commands. + +The \fBmetadata profile\fP is used to override selected configuration +settings at Volume Group/Logical Volume level - it is applied independently +for each Volume Group/Logical Volume that is being processed. As such, +each Volume Group/Logical Volume can store the profile name used +in its metadata so next time the Volume Group/Logical Volume is +processed, the profile is applied automatically. If Volume Group and +any of its Logical Volumes have different profiles defined, the profile +defined for the Logical Volume is preferred. The metadata profile can be +attached/detached by using the \fBlvchange\fP and \fBvgchange\fP commands +and their \fB\-\-metadataprofile ProfileName\fP and +\fB\-\-detachprofile\fP options or the \fB\-\-metadataprofile\fP +option during creation when using \fBvgcreate\fP or \fBlvcreate\fP command. +The \fBvgs\fP and \fBlvs\fP reporting commands provide \fB-o vg_profile\fP +and \fB-o lv_profile\fP output options to show the metadata profile +currently attached to a Volume Group or a Logical Volume. + +The set of options allowed for command profiles is mutually exclusive +when compared to the set of options allowed for metadata profiles. The +settings that belong to either of these two sets can't be mixed together +and LVM tools will reject such profiles. + +LVM itself provides a few predefined configuration profiles. +Users are allowed to add more profiles with different values if needed. +For this purpose, there's the \fBcommand_profile_template.profile\fP +(for command profiles) and \fBmetadata_profile_template.profile\fP +(for metadata profiles) which contain all settings that are customizable +by profiles of certain type. Users are encouraged to copy these template +profiles and edit them as needed. Alternatively, the +\fBlvmconfig \-\-file \-\-type profilable-command
\fP +or \fBlvmconfig \-\-file \-\-type profilable-metadata
\fP +can be used to generate a configuration with profilable settings in either +of the type for given section and save it to new ProfileName.profile +(if the section is not specified, all profilable settings are reported). + +The profiles are stored in #DEFAULT_PROFILE_DIR# directory by default. +This location can be changed by using the \fBconfig/profile_dir\fP setting. +Each profile configuration is stored in \fBProfileName.profile\fP file +in the profile directory. When referencing the profile, the \fB.profile\fP +suffix is left out. + +.TP +.B tag config +.br +See \fBtags\fP configuration setting description below. + +.LP +When several configuration methods are used at the same time +and when LVM looks for the value of a particular setting, it traverses +this \fBconfig cascade\fP from left to right: + +\fBdirect config override on command line\fP -> \fBcommand profile config\fP -> \fBmetadata profile config\fP -> \fBtag config\fP -> \fBlvmlocal.conf\fB -> \fBlvm.conf\fP + +No part of this cascade is compulsory. If there's no setting value found at +the end of the cascade, a default value is used for that setting. +Use \fBlvmconfig\fP to check what settings are in use and what +the default values are. +.SH SYNTAX +.LP +This section describes the configuration file syntax. +.LP +Whitespace is not significant unless it is within quotes. +This provides a wide choice of acceptable indentation styles. +Comments begin with # and continue to the end of the line. +They are treated as whitespace. +.LP +Here is an informal grammar: +.TP +.BR file " = " value * +.br +A configuration file consists of a set of values. +.TP +.BR value " = " section " | " assignment +.br +A value can either be a new section, or an assignment. +.TP +.BR section " = " identifier " '" { "' " value "* '" } ' +.br +A section groups associated values together. If the same section is +encountered multiple times, the contents of all instances are concatenated +together in the order of appearance. +.br +It is denoted by a name and delimited by curly brackets. +.br +e.g. backup { +.br + ... +.br + } +.TP +.BR assignment " = " identifier " '" = "' ( " array " | " type " )" +.br +An assignment associates a type with an identifier. If the identifier contains +forward slashes, those are interpreted as path delimiters. The statement +\fBsection/key = value\fP is equivalent to \fBsection { key = value }\fP. If +multiple instances of the same key are encountered, only the last value is used +(and a warning is issued). +.br +e.g. \fBlevel = 7\fP +.br +.TP +.BR array " = '" [ "' ( " type " '" , "')* " type " '" ] "' | '" [ "' '" ] ' +.br +Inhomogeneous arrays are supported. +.br +Elements must be separated by commas. +.br +An empty array is acceptable. +.TP +.BR type " = " integer " | " float " | " string +.BR integer " = [0-9]*" +.br +.BR float " = [0-9]*'" . '[0-9]* +.br +.B string \fR= '\fB"\fR'.*'\fB"\fR' +.IP +Strings with spaces must be enclosed in double quotes, single words that start +with a letter can be left unquoted. + +.SH SETTINGS + +The +.B lvmconfig +command prints the LVM configuration settings in various ways. +See the man page +.BR lvmconfig (8). + +Command to print a list of all possible config settings, with their +default values: +.br +.B lvmconfig \-\-type default + +Command to print a list of all possible config settings, with their +default values, and a full description of each as a comment: +.br +.B lvmconfig \-\-type default --withcomments + +Command to print a list of all possible config settings, with their +current values (configured, non-default values are shown): +.br +.B lvmconfig \-\-type current + +Command to print all config settings that have been configured with a +different value than the default (configured, non-default values are +shown): +.br +.B lvmconfig \-\-type diff + +Command to print a single config setting, with its default value, +and a full description, where "Section" refers to the config section, +e.g. global, and "Setting" refers to the name of the specific setting, +e.g. umask: +.br +.B lvmconfig \-\-type default --withcomments Section/Setting + + +.SH FILES +.I #DEFAULT_SYS_DIR#/lvm.conf +.br +.I #DEFAULT_SYS_DIR#/lvmlocal.conf +.br +.I #DEFAULT_ARCHIVE_DIR# +.br +.I #DEFAULT_BACKUP_DIR# +.br +.I #DEFAULT_CACHE_DIR#/.cache +.br +.I #DEFAULT_LOCK_DIR# +.br +.I #DEFAULT_PROFILE_DIR# + +.SH SEE ALSO +.BR lvm (8) +.BR lvmconfig (8) + diff --git a/man/lvm2-activation-generator.8.in b/man/lvm2-activation-generator.8.in deleted file mode 100644 index e1be5e1..0000000 --- a/man/lvm2-activation-generator.8.in +++ /dev/null @@ -1,55 +0,0 @@ -.TH "LVM2-ACTIVATION-GENERATOR" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" -.SH "NAME" -lvm2-activation-generator \- generator for systemd units to activate LVM2 volumes on boot -.SH SYNOPSIS -.B #SYSTEMD_GENERATOR_DIR#/lvm2-activation-generator -.sp -.SH DESCRIPTION -The lvm2-activation-generator is called by \fBsystemd\fP(1) on boot -to generate systemd units at runtime to activate LVM2 volumes if -\fBlvmetad\fP(8) is disabled (global/use_lvmetad=0 \fBlvm.conf\fP(5) -option is used). Otherwise, if \fBlvmetad\fP(8) is enabled, -the lvm2-activation-generator exits immediately without generating -any systemd units and LVM2 fully relies on event-based activation -to activate the LVM2 volumes instead using the \fBpvscan\fP(8) -(pvscan \-\-cache -aay) call that is a part of \fBudev\fP(8) rules. - -These systemd units are generated by lvm2-activation-generator: -.sp -\fIlvm2-activation-early.service\fP -used for activation of LVM2 volumes that is ordered before systemd's -special \fBcryptsetup.target\fP to support LVM2 volumes which are not -layered on top of encrypted devices. - -\fIlvm2-activation.service\fP -used for activation of LVM2 volumes that is ordered after systemd's -special \fBcryptsetup.target\fP to support LVM2 volumes which are -layered on top of encrypted devices. - -\fIlvm2-activation-net.service\fP -used for activation of LVM2 volumes that is ordered after systemd's -special \fBremote-fs-pre.target\fP to support LVM2 volumes which are -layered on attached remote devices. - -Note that all the underlying devices (Physical Volumes) need to be present -when the service is run. If the there are any devices presented in the system -anytime later, any LVM2 volumes on top of such devices need to be activated -directly by \fBlvchange\fP(8) or \fBvgchange\fP(8). This limitation does -not exist when using \fBlvmetad\fP(8) and accompanying event-based activation -since such LVM volumes are activated automatically as soon as the Volume Group -is ready (all the Physical Volumes making up the Volume Group are present -in the system). - -The lvm2-activation-generator implements the \fBGenerators Specification\fP -as referenced in \fBsystemd\fP(1). -.sp -.SH SEE ALSO -.BR lvm.conf (5) -.BR vgchange (8) -.BR lvchange (8) -.BR lvmetad (8) -.BR pvscan (8) -.BR udev (7) -.BR systemd (1) -.BR systemd.target (5) -.BR systemd.special (7) diff --git a/man/lvm2-activation-generator.8_main b/man/lvm2-activation-generator.8_main new file mode 100644 index 0000000..e1be5e1 --- /dev/null +++ b/man/lvm2-activation-generator.8_main @@ -0,0 +1,55 @@ +.TH "LVM2-ACTIVATION-GENERATOR" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" +.SH "NAME" +lvm2-activation-generator \- generator for systemd units to activate LVM2 volumes on boot +.SH SYNOPSIS +.B #SYSTEMD_GENERATOR_DIR#/lvm2-activation-generator +.sp +.SH DESCRIPTION +The lvm2-activation-generator is called by \fBsystemd\fP(1) on boot +to generate systemd units at runtime to activate LVM2 volumes if +\fBlvmetad\fP(8) is disabled (global/use_lvmetad=0 \fBlvm.conf\fP(5) +option is used). Otherwise, if \fBlvmetad\fP(8) is enabled, +the lvm2-activation-generator exits immediately without generating +any systemd units and LVM2 fully relies on event-based activation +to activate the LVM2 volumes instead using the \fBpvscan\fP(8) +(pvscan \-\-cache -aay) call that is a part of \fBudev\fP(8) rules. + +These systemd units are generated by lvm2-activation-generator: +.sp +\fIlvm2-activation-early.service\fP +used for activation of LVM2 volumes that is ordered before systemd's +special \fBcryptsetup.target\fP to support LVM2 volumes which are not +layered on top of encrypted devices. + +\fIlvm2-activation.service\fP +used for activation of LVM2 volumes that is ordered after systemd's +special \fBcryptsetup.target\fP to support LVM2 volumes which are +layered on top of encrypted devices. + +\fIlvm2-activation-net.service\fP +used for activation of LVM2 volumes that is ordered after systemd's +special \fBremote-fs-pre.target\fP to support LVM2 volumes which are +layered on attached remote devices. + +Note that all the underlying devices (Physical Volumes) need to be present +when the service is run. If the there are any devices presented in the system +anytime later, any LVM2 volumes on top of such devices need to be activated +directly by \fBlvchange\fP(8) or \fBvgchange\fP(8). This limitation does +not exist when using \fBlvmetad\fP(8) and accompanying event-based activation +since such LVM volumes are activated automatically as soon as the Volume Group +is ready (all the Physical Volumes making up the Volume Group are present +in the system). + +The lvm2-activation-generator implements the \fBGenerators Specification\fP +as referenced in \fBsystemd\fP(1). +.sp +.SH SEE ALSO +.BR lvm.conf (5) +.BR vgchange (8) +.BR lvchange (8) +.BR lvmetad (8) +.BR pvscan (8) +.BR udev (7) +.BR systemd (1) +.BR systemd.target (5) +.BR systemd.special (7) diff --git a/man/lvmcache.7.in b/man/lvmcache.7.in deleted file mode 100644 index 45bb5b1..0000000 --- a/man/lvmcache.7.in +++ /dev/null @@ -1,419 +0,0 @@ -.TH "LVMCACHE" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" -.SH NAME -lvmcache \(em LVM caching - -.SH DESCRIPTION - -The \fBcache\fP logical volume type uses a small and fast LV to improve -the performance of a large and slow LV. It does this by storing the -frequently used blocks on the faster LV. -LVM refers to the small fast LV as a \fBcache pool LV\fP. The large -slow LV is called the \fBorigin LV\fP. Due to requirements from dm-cache -(the kernel driver), LVM further splits the cache pool LV into two -devices - the \fBcache data LV\fP and \fBcache metadata LV\fP. The cache -data LV is where copies of data blocks are kept from the -origin LV to increase speed. The cache metadata LV holds the -accounting information that specifies where data blocks are stored (e.g. -on the origin LV or on the cache data LV). Users should be familiar with -these LVs if they wish to create the best and most robust cached -logical volumes. All of these associated LVs must be in the same VG. - -.SH Cache Terms -.nf -origin LV OriginLV large slow LV -cache data LV CacheDataLV small fast LV for cache pool data -cache metadata LV CacheMetaLV small fast LV for cache pool metadata -cache pool LV CachePoolLV CacheDataLV + CacheMetaLV -cache LV CacheLV OriginLV + CachePoolLV -.fi - -.SH Cache Usage - -The primary method for using a cache type logical volume: - - -.SS 0. create OriginLV - -Create an LV or identify an existing LV to be the origin LV. - -.B lvcreate \-n OriginLV \-L LargeSize VG SlowPVs - -.I Example -.br -# lvcreate \-n lvol0 \-L 100G vg - - -.SS 1. create CacheDataLV - -Create the cache data LV. This LV will hold data blocks from the -OriginLV. The size of this LV is the size of the cache and will be -reported as the size of the cache pool LV. - -.B lvcreate \-n CacheDataLV \-L CacheSize VG FastPVs - -.I Example -.br -# lvcreate \-n cache0 \-L 10G vg /dev/fast - - -.SS 2. create CacheMetaLV - -Create the cache metadata LV. This LV will hold cache pool metadata. The -size of this LV should be 1000 times smaller than the cache data LV, with -a minimum size of 8MiB. - -.B lvcreate \-n CacheMetaLV \-L MetaSize VG FastPVs - -.I Example -.br -# lvcreate \-n cache0meta \-L 12M vg /dev/fast - -.nf -# lvs -a vg - LV VG Attr LSize Pool Origin - cache0 vg -wi-a----- 10.00g - cache0meta vg -wi-a----- 12.00m - lvol0 vg -wi-a----- 100.00g -.fi - - -.SS 3. create CachePoolLV - -Combine the data and metadata LVs into a cache pool LV. -The behavior of the cache pool LV can be set in this step. -.br -CachePoolLV takes the name of CacheDataLV. -.br -CacheDataLV is renamed CachePoolLV_cdata and becomes hidden. -.br -CacheMetaLV is renamed CachePoolLV_cmeta and becomes hidden. - -.B lvconvert \-\-type cache-pool \-\-poolmetadata VG/CacheMetaLV -.RS -.B VG/CacheDataLV -.RE - -.I Example -.br -# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache0meta vg/cache0 - -.nf -# lvs -a vg - LV VG Attr LSize Pool Origin - cache0 vg Cwi---C--- 10.00g - [cache0_cdata] vg Cwi------- 10.00g - [cache0_cmeta] vg ewi------- 12.00m - lvol0 vg -wi-a----- 100.00g -.fi - - -.SS 4. create CacheLV - -Create a cache LV by linking the cache pool LV to the origin LV. -The user accessible cache LV takes the name of the origin LV, -while the origin LV becomes a hidden LV with the name -OriginLV_corig. This can be done while the origin LV is in use. -.br -CacheLV takes the name of OriginLV. -.br -OriginLV is renamed OriginLV_corig and becomes hidden. - -.B lvconvert \-\-type cache \-\-cachepool VG/CachePoolLV VG/OriginLV - -.I Example -.br -# lvconvert \-\-type cache \-\-cachepool vg/cache0 vg/lvol0 - -.nf -# lvs -a vg - LV VG Attr LSize Pool Origin - cache0 vg Cwi---C--- 10.00g - [cache0_cdata] vg Cwi-ao---- 10.00g - [cache0_cmeta] vg ewi-ao---- 12.00m - lvol0 vg Cwi-a-C--- 100.00g cache0 [lvol0_corig] - [lvol0_corig] vg -wi-ao---- 100.00g -.fi - - -.SH Cache Removal - -.SS Split a cache pool LV off of a cache LV - -\& - -A cache pool LV can be disconnected from a cache LV, leaving an -unused cache pool LV, and an uncached origin LV. This command -writes back data from the cache pool to the origin LV when necessary. - -.B lvconvert --splitcache VG/CacheLV - -.SS Removing a cache pool LV without removing its linked origin LV - -\& - -This writes back data from the cache pool to the origin LV when necessary, -then removes the cache pool LV, leaving the uncached origin LV. - -.B lvremove VG/CachePoolLV - -An alternative command that also disconnects the cache pool from the cache -LV, and deletes the cache pool: - -.B lvconvert --uncache VG/CacheLV - -.I Example -.nf -# lvs vg - LV VG Attr LSize Pool Origin - cache0 vg Cwi---C--- 10.00g - lvol0 vg Cwi-a-C--- 100.00g cache0 [lvol0_corig] - -# lvremove vg/cache0 - -# lvs vg - LV VG Attr LSize Pool Origin - lvol0 vg -wi-a----- 100.00g -.fi - -.SS Removing a cache LV: both origin LV and the cache pool LV - -\& - -Removing a cache LV removes both the origin LV and the linked cache pool -LV. - -.B lvremove VG/CacheLV - - -.SH Cache Topics - -.SS Tolerate device failures in a cache pool LV - -\& - -Users who are concerned about the possibility of failures in their fast -devices that could lead to data loss might consider making their cache -pool sub-LVs redundant. - -.I Example -.nf -0. Create an origin LV we wish to cache -# lvcreate \-L 10G \-n lv1 vg /dev/slow_devs - -1. Create a 2-way RAID1 cache data LV -# lvcreate \-\-type raid1 \-m 1 \-L 1G -n cache1 vg \\ - /dev/fast1 /dev/fast2 - -2. Create a 2-way RAID1 cache metadata LV -# lvcreate \-\-type raid1 \-m 1 \-L 8M -n cache1meta vg \\ - /dev/fast1 /dev/fast2 - -3. Create a cache pool LV combining cache data LV and cache metadata LV -# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache1meta vg/cache1 - -4. Create a cached LV by combining the cache pool LV and origin LV -# lvconvert \-\-type cache \-\-cachepool vg/cache1 vg/lv1 -.fi - -.SS Cache mode - -\& - -The default cache mode is "writethrough". Writethrough ensures that any -data written will be stored both in the cache pool LV and on the origin -LV. The loss of a device associated with the cache pool LV in this case -would not mean the loss of any data. - -A second cache mode is "writeback". Writeback delays writing data blocks -from the cache pool back to the origin LV. This mode will increase -performance, but the loss of a device associated with the cache pool LV -can result in lost data. - -With the \-\-cachemode option, the cache mode can be set when creating a -cache LV, or changed on an existing cache LV. The current cache mode of a -cache LV can be displayed with the cache_mode reporting option: - -.B lvs \-o+cache_mode VG/CacheLV - -.BR lvm.conf (5) -.B allocation/cache_mode -.br -defines the default cache mode. - -.I Example -.nf -0. Create an origin LV we wish to cache (yours may already exist) -# lvcreate \-L 10G \-n lv1 vg /dev/slow - -1. Create a cache data LV -# lvcreate \-L 1G \-n cache1 vg /dev/fast - -2. Create a cache metadata LV -# lvcreate \-L 8M \-n cache1meta vg /dev/fast - -3. Create a cache pool LV -# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache1meta vg/cache1 - -4. Create a cache LV by combining the cache pool LV and origin LV, - and use the writethrough cache mode. -# lvconvert \-\-type cache \-\-cachepool vg/cache1 \\ - \-\-cachemode writethrough vg/lv1 -.fi - - -.SS Cache policy - -\& - -The cache subsystem has additional per-LV parameters: the cache policy to -use, and possibly tunable parameters for the cache policy. Three policies -are currently available: "smq" is the default policy, "mq" is an older -implementation, and "cleaner" is used to force the cache to write back -(flush) all cached writes to the origin LV. - -The "mq" policy has a number of tunable parameters. The defaults are -chosen to be suitable for the majority of systems, but in special -circumstances, changing the settings can improve performance. - -With the \-\-cachepolicy and \-\-cachesettings options, the cache policy -and settings can be set when creating a cache LV, or changed on an -existing cache LV (both options can be used together). The current cache -policy and settings of a cache LV can be displayed with the cache_policy -and cache_settings reporting options: - -.B lvs \-o+cache_policy,cache_settings VG/CacheLV - -.I Example -.nf -Change the cache policy and settings of an existing cache LV. -# lvchange \-\-cachepolicy mq \-\-cachesettings \\ - \(aqmigration_threshold=2048 random_threshold=4\(aq vg/lv1 -.fi - -.BR lvm.conf (5) -.B allocation/cache_policy -.br -defines the default cache policy. - -.BR lvm.conf (5) -.B allocation/cache_settings -.br -defines the default cache settings. - - -.SS Chunk size - -\& - -The size of data blocks managed by a cache pool can be specified with the -\-\-chunksize option when the cache LV is created. The default unit -is KiB. The value must be a multiple of 32KiB between 32KiB and 1GiB. - -Using a chunk size that is too large can result in wasteful use of the -cache, where small reads and writes can cause large sections of an LV to -be mapped into the cache. However, choosing a chunk size that is too -small can result in more overhead trying to manage the numerous chunks -that become mapped into the cache. Overhead can include both excessive -CPU time searching for chunks, and excessive memory tracking chunks. - -Command to display the cache pool LV chunk size: -.br -.B lvs \-o+chunksize VG/CacheLV - -.BR lvm.conf (5) -.B cache_pool_chunk_size -.br -controls the default chunk size used when creating a cache LV. - -The default value is shown by: -.br -.B lvmconfig \-\-type default allocation/cache_pool_chunk_size - - -.SS Spare metadata LV - -\& - -See -.BR lvmthin (7) -for a description of the "pool metadata spare" LV. -The same concept is used for cache pools. - -.SS Automatic pool metadata LV - -\& - -A cache data LV can be converted to cache pool LV without specifying a -cache pool metadata LV. LVM will automatically create a metadata LV from -the same VG. - -.B lvcreate -n CacheDataLV -L CacheSize VG -.br -.B lvconvert --type cache\-pool VG/CacheDataLV - - -.SS Create a new cache LV without an existing origin LV - -\& - -A cache LV can be created using an existing cache pool without an existing -origin LV. A new origin LV is created and linked to the cache pool in a -single step. - -.B lvcreate \-\-type cache \-L LargeSize \-n CacheLV -.RS -.B \-\-cachepool VG/CachePoolLV VG SlowPVs -.RE - - -.SS Single step cache pool LV creation - -\& - -A cache pool LV can be created with a single lvcreate command, rather than -using lvconvert on existing LVs. This one command creates a cache data -LV, a cache metadata LV, and combines the two into a cache pool LV. - -.B lvcreate \-\-type cache\-pool \-L CacheSize \-n CachePoolLV VG FastPVs - - -.SS Convert existing LVs to cache types - -\& - -When an existing origin LV is converted to a cache LV, the specified cache -pool may be a normal LV, rather than a cache pool LV. In this case, lvm -will first convert the normal LV to a cache pool LV. A pool metadata LV -may optionally be specified. - -.B lvcreate -n OriginLV -L LargeSize VG -.br -.B lvcreate -n CacheDataLV -L CacheSize VG -.br -.B lvconvert --type cache --cachepool VG/CataDataLV VG/OriginLV - -This is equivalent to: - -.B lvcreate -n OriginLV -L LargeSize VG -.br -.B lvcreate -n CacheDataLV -L CacheSize VG -.br -.B lvconvert --type cache-pool VG/CacheDataLV -.br -.B lvconvert --type cache --cachepool VG/CachePoolLV VG/OriginLV - - -.SH SEE ALSO -.BR lvm.conf (5), -.BR lvchange (8), -.BR lvcreate (8), -.BR lvdisplay (8), -.BR lvextend (8), -.BR lvremove (8), -.BR lvrename (8), -.BR lvresize (8), -.BR lvs (8), -.BR vgchange (8), -.BR vgmerge (8), -.BR vgreduce (8), -.BR vgsplit (8) diff --git a/man/lvmcache.7_main b/man/lvmcache.7_main new file mode 100644 index 0000000..45bb5b1 --- /dev/null +++ b/man/lvmcache.7_main @@ -0,0 +1,419 @@ +.TH "LVMCACHE" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" +.SH NAME +lvmcache \(em LVM caching + +.SH DESCRIPTION + +The \fBcache\fP logical volume type uses a small and fast LV to improve +the performance of a large and slow LV. It does this by storing the +frequently used blocks on the faster LV. +LVM refers to the small fast LV as a \fBcache pool LV\fP. The large +slow LV is called the \fBorigin LV\fP. Due to requirements from dm-cache +(the kernel driver), LVM further splits the cache pool LV into two +devices - the \fBcache data LV\fP and \fBcache metadata LV\fP. The cache +data LV is where copies of data blocks are kept from the +origin LV to increase speed. The cache metadata LV holds the +accounting information that specifies where data blocks are stored (e.g. +on the origin LV or on the cache data LV). Users should be familiar with +these LVs if they wish to create the best and most robust cached +logical volumes. All of these associated LVs must be in the same VG. + +.SH Cache Terms +.nf +origin LV OriginLV large slow LV +cache data LV CacheDataLV small fast LV for cache pool data +cache metadata LV CacheMetaLV small fast LV for cache pool metadata +cache pool LV CachePoolLV CacheDataLV + CacheMetaLV +cache LV CacheLV OriginLV + CachePoolLV +.fi + +.SH Cache Usage + +The primary method for using a cache type logical volume: + + +.SS 0. create OriginLV + +Create an LV or identify an existing LV to be the origin LV. + +.B lvcreate \-n OriginLV \-L LargeSize VG SlowPVs + +.I Example +.br +# lvcreate \-n lvol0 \-L 100G vg + + +.SS 1. create CacheDataLV + +Create the cache data LV. This LV will hold data blocks from the +OriginLV. The size of this LV is the size of the cache and will be +reported as the size of the cache pool LV. + +.B lvcreate \-n CacheDataLV \-L CacheSize VG FastPVs + +.I Example +.br +# lvcreate \-n cache0 \-L 10G vg /dev/fast + + +.SS 2. create CacheMetaLV + +Create the cache metadata LV. This LV will hold cache pool metadata. The +size of this LV should be 1000 times smaller than the cache data LV, with +a minimum size of 8MiB. + +.B lvcreate \-n CacheMetaLV \-L MetaSize VG FastPVs + +.I Example +.br +# lvcreate \-n cache0meta \-L 12M vg /dev/fast + +.nf +# lvs -a vg + LV VG Attr LSize Pool Origin + cache0 vg -wi-a----- 10.00g + cache0meta vg -wi-a----- 12.00m + lvol0 vg -wi-a----- 100.00g +.fi + + +.SS 3. create CachePoolLV + +Combine the data and metadata LVs into a cache pool LV. +The behavior of the cache pool LV can be set in this step. +.br +CachePoolLV takes the name of CacheDataLV. +.br +CacheDataLV is renamed CachePoolLV_cdata and becomes hidden. +.br +CacheMetaLV is renamed CachePoolLV_cmeta and becomes hidden. + +.B lvconvert \-\-type cache-pool \-\-poolmetadata VG/CacheMetaLV +.RS +.B VG/CacheDataLV +.RE + +.I Example +.br +# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache0meta vg/cache0 + +.nf +# lvs -a vg + LV VG Attr LSize Pool Origin + cache0 vg Cwi---C--- 10.00g + [cache0_cdata] vg Cwi------- 10.00g + [cache0_cmeta] vg ewi------- 12.00m + lvol0 vg -wi-a----- 100.00g +.fi + + +.SS 4. create CacheLV + +Create a cache LV by linking the cache pool LV to the origin LV. +The user accessible cache LV takes the name of the origin LV, +while the origin LV becomes a hidden LV with the name +OriginLV_corig. This can be done while the origin LV is in use. +.br +CacheLV takes the name of OriginLV. +.br +OriginLV is renamed OriginLV_corig and becomes hidden. + +.B lvconvert \-\-type cache \-\-cachepool VG/CachePoolLV VG/OriginLV + +.I Example +.br +# lvconvert \-\-type cache \-\-cachepool vg/cache0 vg/lvol0 + +.nf +# lvs -a vg + LV VG Attr LSize Pool Origin + cache0 vg Cwi---C--- 10.00g + [cache0_cdata] vg Cwi-ao---- 10.00g + [cache0_cmeta] vg ewi-ao---- 12.00m + lvol0 vg Cwi-a-C--- 100.00g cache0 [lvol0_corig] + [lvol0_corig] vg -wi-ao---- 100.00g +.fi + + +.SH Cache Removal + +.SS Split a cache pool LV off of a cache LV + +\& + +A cache pool LV can be disconnected from a cache LV, leaving an +unused cache pool LV, and an uncached origin LV. This command +writes back data from the cache pool to the origin LV when necessary. + +.B lvconvert --splitcache VG/CacheLV + +.SS Removing a cache pool LV without removing its linked origin LV + +\& + +This writes back data from the cache pool to the origin LV when necessary, +then removes the cache pool LV, leaving the uncached origin LV. + +.B lvremove VG/CachePoolLV + +An alternative command that also disconnects the cache pool from the cache +LV, and deletes the cache pool: + +.B lvconvert --uncache VG/CacheLV + +.I Example +.nf +# lvs vg + LV VG Attr LSize Pool Origin + cache0 vg Cwi---C--- 10.00g + lvol0 vg Cwi-a-C--- 100.00g cache0 [lvol0_corig] + +# lvremove vg/cache0 + +# lvs vg + LV VG Attr LSize Pool Origin + lvol0 vg -wi-a----- 100.00g +.fi + +.SS Removing a cache LV: both origin LV and the cache pool LV + +\& + +Removing a cache LV removes both the origin LV and the linked cache pool +LV. + +.B lvremove VG/CacheLV + + +.SH Cache Topics + +.SS Tolerate device failures in a cache pool LV + +\& + +Users who are concerned about the possibility of failures in their fast +devices that could lead to data loss might consider making their cache +pool sub-LVs redundant. + +.I Example +.nf +0. Create an origin LV we wish to cache +# lvcreate \-L 10G \-n lv1 vg /dev/slow_devs + +1. Create a 2-way RAID1 cache data LV +# lvcreate \-\-type raid1 \-m 1 \-L 1G -n cache1 vg \\ + /dev/fast1 /dev/fast2 + +2. Create a 2-way RAID1 cache metadata LV +# lvcreate \-\-type raid1 \-m 1 \-L 8M -n cache1meta vg \\ + /dev/fast1 /dev/fast2 + +3. Create a cache pool LV combining cache data LV and cache metadata LV +# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache1meta vg/cache1 + +4. Create a cached LV by combining the cache pool LV and origin LV +# lvconvert \-\-type cache \-\-cachepool vg/cache1 vg/lv1 +.fi + +.SS Cache mode + +\& + +The default cache mode is "writethrough". Writethrough ensures that any +data written will be stored both in the cache pool LV and on the origin +LV. The loss of a device associated with the cache pool LV in this case +would not mean the loss of any data. + +A second cache mode is "writeback". Writeback delays writing data blocks +from the cache pool back to the origin LV. This mode will increase +performance, but the loss of a device associated with the cache pool LV +can result in lost data. + +With the \-\-cachemode option, the cache mode can be set when creating a +cache LV, or changed on an existing cache LV. The current cache mode of a +cache LV can be displayed with the cache_mode reporting option: + +.B lvs \-o+cache_mode VG/CacheLV + +.BR lvm.conf (5) +.B allocation/cache_mode +.br +defines the default cache mode. + +.I Example +.nf +0. Create an origin LV we wish to cache (yours may already exist) +# lvcreate \-L 10G \-n lv1 vg /dev/slow + +1. Create a cache data LV +# lvcreate \-L 1G \-n cache1 vg /dev/fast + +2. Create a cache metadata LV +# lvcreate \-L 8M \-n cache1meta vg /dev/fast + +3. Create a cache pool LV +# lvconvert \-\-type cache\-pool \-\-poolmetadata vg/cache1meta vg/cache1 + +4. Create a cache LV by combining the cache pool LV and origin LV, + and use the writethrough cache mode. +# lvconvert \-\-type cache \-\-cachepool vg/cache1 \\ + \-\-cachemode writethrough vg/lv1 +.fi + + +.SS Cache policy + +\& + +The cache subsystem has additional per-LV parameters: the cache policy to +use, and possibly tunable parameters for the cache policy. Three policies +are currently available: "smq" is the default policy, "mq" is an older +implementation, and "cleaner" is used to force the cache to write back +(flush) all cached writes to the origin LV. + +The "mq" policy has a number of tunable parameters. The defaults are +chosen to be suitable for the majority of systems, but in special +circumstances, changing the settings can improve performance. + +With the \-\-cachepolicy and \-\-cachesettings options, the cache policy +and settings can be set when creating a cache LV, or changed on an +existing cache LV (both options can be used together). The current cache +policy and settings of a cache LV can be displayed with the cache_policy +and cache_settings reporting options: + +.B lvs \-o+cache_policy,cache_settings VG/CacheLV + +.I Example +.nf +Change the cache policy and settings of an existing cache LV. +# lvchange \-\-cachepolicy mq \-\-cachesettings \\ + \(aqmigration_threshold=2048 random_threshold=4\(aq vg/lv1 +.fi + +.BR lvm.conf (5) +.B allocation/cache_policy +.br +defines the default cache policy. + +.BR lvm.conf (5) +.B allocation/cache_settings +.br +defines the default cache settings. + + +.SS Chunk size + +\& + +The size of data blocks managed by a cache pool can be specified with the +\-\-chunksize option when the cache LV is created. The default unit +is KiB. The value must be a multiple of 32KiB between 32KiB and 1GiB. + +Using a chunk size that is too large can result in wasteful use of the +cache, where small reads and writes can cause large sections of an LV to +be mapped into the cache. However, choosing a chunk size that is too +small can result in more overhead trying to manage the numerous chunks +that become mapped into the cache. Overhead can include both excessive +CPU time searching for chunks, and excessive memory tracking chunks. + +Command to display the cache pool LV chunk size: +.br +.B lvs \-o+chunksize VG/CacheLV + +.BR lvm.conf (5) +.B cache_pool_chunk_size +.br +controls the default chunk size used when creating a cache LV. + +The default value is shown by: +.br +.B lvmconfig \-\-type default allocation/cache_pool_chunk_size + + +.SS Spare metadata LV + +\& + +See +.BR lvmthin (7) +for a description of the "pool metadata spare" LV. +The same concept is used for cache pools. + +.SS Automatic pool metadata LV + +\& + +A cache data LV can be converted to cache pool LV without specifying a +cache pool metadata LV. LVM will automatically create a metadata LV from +the same VG. + +.B lvcreate -n CacheDataLV -L CacheSize VG +.br +.B lvconvert --type cache\-pool VG/CacheDataLV + + +.SS Create a new cache LV without an existing origin LV + +\& + +A cache LV can be created using an existing cache pool without an existing +origin LV. A new origin LV is created and linked to the cache pool in a +single step. + +.B lvcreate \-\-type cache \-L LargeSize \-n CacheLV +.RS +.B \-\-cachepool VG/CachePoolLV VG SlowPVs +.RE + + +.SS Single step cache pool LV creation + +\& + +A cache pool LV can be created with a single lvcreate command, rather than +using lvconvert on existing LVs. This one command creates a cache data +LV, a cache metadata LV, and combines the two into a cache pool LV. + +.B lvcreate \-\-type cache\-pool \-L CacheSize \-n CachePoolLV VG FastPVs + + +.SS Convert existing LVs to cache types + +\& + +When an existing origin LV is converted to a cache LV, the specified cache +pool may be a normal LV, rather than a cache pool LV. In this case, lvm +will first convert the normal LV to a cache pool LV. A pool metadata LV +may optionally be specified. + +.B lvcreate -n OriginLV -L LargeSize VG +.br +.B lvcreate -n CacheDataLV -L CacheSize VG +.br +.B lvconvert --type cache --cachepool VG/CataDataLV VG/OriginLV + +This is equivalent to: + +.B lvcreate -n OriginLV -L LargeSize VG +.br +.B lvcreate -n CacheDataLV -L CacheSize VG +.br +.B lvconvert --type cache-pool VG/CacheDataLV +.br +.B lvconvert --type cache --cachepool VG/CachePoolLV VG/OriginLV + + +.SH SEE ALSO +.BR lvm.conf (5), +.BR lvchange (8), +.BR lvcreate (8), +.BR lvdisplay (8), +.BR lvextend (8), +.BR lvremove (8), +.BR lvrename (8), +.BR lvresize (8), +.BR lvs (8), +.BR vgchange (8), +.BR vgmerge (8), +.BR vgreduce (8), +.BR vgsplit (8) diff --git a/man/lvmconf.8.in b/man/lvmconf.8.in deleted file mode 100644 index 44cb52b..0000000 --- a/man/lvmconf.8.in +++ /dev/null @@ -1,70 +0,0 @@ -.TH "LVMCONF" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" - -.SH "NAME" -lvmconf \(em LVM configuration modifier -.SH "SYNOPSIS" -.B lvmconf -.RB [ \-\-disable-cluster ] -.RB [ \-\-enable-cluster ] -.RB [ \-\-enable-halvm ] -.RB [ \-\-disable-halvm ] -.RB [ \-\-file -.RI < configfile >] -.RB [ \-\-lockinglib -.RI < lib >] -.RB [ \-\-lockinglibdir -.RI < dir >] -.RB [ \-\-services ] -.RB [ \-\-mirrorservice ] -.RB [ \-\-startstopservices ] - -.SH "DESCRIPTION" -lvmconf is a script that modifies the locking configuration in -an lvm configuration file. See \fBlvm.conf\fP(5). In addition -to that, it can also set Systemd or SysV services according to -changes in the lvm configuration if needed. - -.SH "OPTIONS" -.TP -.BR \-\-disable-cluster -Set \fBlocking_type\fR to the default non-clustered type. Also reset -lvmetad use to its default. -.TP -.BR \-\-enable-cluster -Set \fBlocking_type\fR to the default clustered type on this system. -Also disable lvmetad use as it is not yet supported in clustered environment. -.TP -.BR \-\-disable-halvm -Set \fBlocking_type\fR to the default non-clustered type. Also reset -lvmetad use to its default. -.TP -.BR \-\-enable-halvm -Set \fBlocking_type\fR suitable for HA LVM use. -Also disable lvmetad use as it is not yet supported in HA LVM environment. -.TP -.BR \-\-file " <" \fIconfigfile > -Apply the changes to \fIconfigfile\fP instead of the default -\fI#DEFAULT_SYS_DIR#/lvm.conf\fP. -.TP -.BR \-\-lockinglib " <" \fIlib > -Set external \fBlocking_library\fR locking library to load if an external locking type is used. -.TP -.BR \-\-lockinglibdir " <" \fIdir > -.TP -.BR \-\-services -In addition to setting the lvm configuration, also enable or disable related Systemd or SysV -clvmd and lvmetad services. This script does not configure services provided by cluster resource -agents. -.TP -.BR \-\-mirrorservice -Also enable or disable optional cmirrord service when handling services (applicable only with \-\-services). -.TP -.BR \-\-startstopservices -In addition to enabling or disabling related services, start or stop them immediately -(applicable only with \-\-services). -.SH FILES -.I #DEFAULT_SYS_DIR#/lvm.conf - -.SH "SEE ALSO" -.BR lvm (8), -.BR lvm.conf (5) diff --git a/man/lvmconf.8_main b/man/lvmconf.8_main new file mode 100644 index 0000000..44cb52b --- /dev/null +++ b/man/lvmconf.8_main @@ -0,0 +1,70 @@ +.TH "LVMCONF" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" + +.SH "NAME" +lvmconf \(em LVM configuration modifier +.SH "SYNOPSIS" +.B lvmconf +.RB [ \-\-disable-cluster ] +.RB [ \-\-enable-cluster ] +.RB [ \-\-enable-halvm ] +.RB [ \-\-disable-halvm ] +.RB [ \-\-file +.RI < configfile >] +.RB [ \-\-lockinglib +.RI < lib >] +.RB [ \-\-lockinglibdir +.RI < dir >] +.RB [ \-\-services ] +.RB [ \-\-mirrorservice ] +.RB [ \-\-startstopservices ] + +.SH "DESCRIPTION" +lvmconf is a script that modifies the locking configuration in +an lvm configuration file. See \fBlvm.conf\fP(5). In addition +to that, it can also set Systemd or SysV services according to +changes in the lvm configuration if needed. + +.SH "OPTIONS" +.TP +.BR \-\-disable-cluster +Set \fBlocking_type\fR to the default non-clustered type. Also reset +lvmetad use to its default. +.TP +.BR \-\-enable-cluster +Set \fBlocking_type\fR to the default clustered type on this system. +Also disable lvmetad use as it is not yet supported in clustered environment. +.TP +.BR \-\-disable-halvm +Set \fBlocking_type\fR to the default non-clustered type. Also reset +lvmetad use to its default. +.TP +.BR \-\-enable-halvm +Set \fBlocking_type\fR suitable for HA LVM use. +Also disable lvmetad use as it is not yet supported in HA LVM environment. +.TP +.BR \-\-file " <" \fIconfigfile > +Apply the changes to \fIconfigfile\fP instead of the default +\fI#DEFAULT_SYS_DIR#/lvm.conf\fP. +.TP +.BR \-\-lockinglib " <" \fIlib > +Set external \fBlocking_library\fR locking library to load if an external locking type is used. +.TP +.BR \-\-lockinglibdir " <" \fIdir > +.TP +.BR \-\-services +In addition to setting the lvm configuration, also enable or disable related Systemd or SysV +clvmd and lvmetad services. This script does not configure services provided by cluster resource +agents. +.TP +.BR \-\-mirrorservice +Also enable or disable optional cmirrord service when handling services (applicable only with \-\-services). +.TP +.BR \-\-startstopservices +In addition to enabling or disabling related services, start or stop them immediately +(applicable only with \-\-services). +.SH FILES +.I #DEFAULT_SYS_DIR#/lvm.conf + +.SH "SEE ALSO" +.BR lvm (8), +.BR lvm.conf (5) diff --git a/man/lvmconfig.8.des b/man/lvmconfig.8.des deleted file mode 100644 index 17f9f18..0000000 --- a/man/lvmconfig.8.des +++ /dev/null @@ -1,3 +0,0 @@ -lvmconfig produces formatted output from the LVM configuration tree. The -sources of the configuration data include \fBlvm.conf\fP(5) and command -line settings from \-\-config. diff --git a/man/lvmconfig.8_des b/man/lvmconfig.8_des new file mode 100644 index 0000000..17f9f18 --- /dev/null +++ b/man/lvmconfig.8_des @@ -0,0 +1,3 @@ +lvmconfig produces formatted output from the LVM configuration tree. The +sources of the configuration data include \fBlvm.conf\fP(5) and command +line settings from \-\-config. diff --git a/man/lvmconfig.8_end b/man/lvmconfig.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvmconfig.8_pregen b/man/lvmconfig.8_pregen new file mode 100644 index 0000000..e3bfdfc --- /dev/null +++ b/man/lvmconfig.8_pregen @@ -0,0 +1,520 @@ +.TH LVMCONFIG 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvmconfig \- Display and manipulate configuration information +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvmconfig\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +lvmconfig produces formatted output from the LVM configuration tree. The +sources of the configuration data include \fBlvm.conf\fP(5) and command +line settings from \-\-config. + +.P +.SH USAGE +.br +.P +. +\fBlvmconfig\fP +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--file\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-l\fP|\fB--list\fP ] +.ad b +.br +.ad l +[ \fB--atversion\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--typeconfig\fP \fBcurrent\fP|\fBdefault\fP|\fBdiff\fP|\fBfull\fP|\fBlist\fP|\fBmissing\fP|\fBnew\fP|\fBprofilable\fP|\fBprofilable-command\fP|\fBprofilable-metadata\fP ] +.ad b +.br +.ad l +[ \fB--ignoreadvanced\fP ] +.ad b +.br +.ad l +[ \fB--ignoreunsupported\fP ] +.ad b +.br +.ad l +[ \fB--ignorelocal\fP ] +.ad b +.br +.ad l +[ \fB--mergedconfig\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--sinceversion\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--showdeprecated\fP ] +.ad b +.br +.ad l +[ \fB--showunsupported\fP ] +.ad b +.br +.ad l +[ \fB--validate\fP ] +.ad b +.br +.ad l +[ \fB--withsummary\fP ] +.ad b +.br +.ad l +[ \fB--withcomments\fP ] +.ad b +.br +.ad l +[ \fB--withspaces\fP ] +.ad b +.br +.ad l +[ \fB--unconfigured\fP ] +.ad b +.br +.ad l +[ \fB--withversions\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIString\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--atversion\fP \fIString\fP +.br +Specify an LVM version in x.y.z format where x is the major version, +the y is the minor version and z is the patchlevel (e.g. 2.2.106). +When configuration is displayed, the configuration settings recognized +at this LVM version will be considered only. This can be used +to display a configuration that a certain LVM version understands and +which does not contain any newer settings for which LVM would +issue a warning message when checking the configuration. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--file\fP \fIString\fP +.br +Write output to the named file. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignoreadvanced\fP +.br +Exclude advanced configuration settings from the output. +.ad b + +.HP +.ad l +\fB--ignorelocal\fP +.br +Ignore local section. +.ad b + +.HP +.ad l +\fB--ignoreunsupported\fP +.br +Exclude unsupported configuration settings from the output. These settings are +either used for debugging and development purposes only or their support is not +yet complete and they are not meant to be used in production. The \fBcurrent\fP +and \fBdiff\fP types include unsupported settings in their output by default, +all the other types ignore unsupported settings. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--list\fP +.br +List config settings with summarizing comment. This is the same as using +options --typeconfig list --withsummary. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--mergedconfig\fP +.br +When the command is run with --config +and/or --commandprofile (or using LVM_COMMAND_PROFILE +environment variable), --profile, or --metadataprofile, +merge all the contents of the "config cascade" before displaying it. +Without merging, only the configuration at the front of the +cascade is displayed. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--metadataprofile\fP \fIString\fP +.br +The metadata profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--showdeprecated\fP +.br +Include deprecated configuration settings in the output. These settings +are deprecated after a certain version. If a concrete version is specified +with --atversion, deprecated settings are automatically included +if the specified version is lower than the version in which the settings were +deprecated. The current and diff types include deprecated settings +in their output by default, all the other types ignore deprecated settings. +.ad b + +.HP +.ad l +\fB--showunsupported\fP +.br +Include unsupported configuration settings in the output. These settings +are either used for debugging or development purposes only, or their support +is not yet complete and they are not meant to be used in production. The +current and diff types include unsupported settings in their +output by default, all the other types ignore unsupported settings. +.ad b + +.HP +.ad l +\fB--sinceversion\fP \fIString\fP +.br +Specify an LVM version in x.y.z format where x is the major version, +the y is the minor version and z is the patchlevel (e.g. 2.2.106). +This option is currently applicable only with --typeconfig new +to display all configuration settings introduced since given version. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--typeconfig\fP \fBcurrent\fP|\fBdefault\fP|\fBdiff\fP|\fBfull\fP|\fBlist\fP|\fBmissing\fP|\fBnew\fP|\fBprofilable\fP|\fBprofilable-command\fP|\fBprofilable-metadata\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB--unconfigured\fP +.br +Internal option used for generating config file during build. +.ad b + +.HP +.ad l +\fB--validate\fP +.br +Validate current configuration used and exit with appropriate +return code. The validation is done only for the configuration +at the front of the "config cascade". To validate the whole +merged configuration tree, also use --mergedconfig. +The validation is done even if lvm.conf config/checks is disabled. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB--withcomments\fP +.br +Display a full comment for each configuration node. For deprecated +settings, also display comments about deprecation. +.ad b + +.HP +.ad l +\fB--withspaces\fP +.br +Where appropriate, add more spaces in output for better readability. +.ad b + +.HP +.ad l +\fB--withsummary\fP +.br +Display a one line comment for each configuration node. +.ad b + +.HP +.ad l +\fB--withversions\fP +.br +Also display a comment containing the version of introduction for +each configuration node. If the setting is deprecated, also display +the version since which it is deprecated. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvmdbusd.8.in b/man/lvmdbusd.8.in deleted file mode 100644 index 9e035f5..0000000 --- a/man/lvmdbusd.8.in +++ /dev/null @@ -1,38 +0,0 @@ -.TH LVMDBUSD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- -. -.SH NAME -. -lvmdbusd \(em LVM D-Bus daemon -. -.SH SYNOPSIS -. -.ad l -.B lvmdbusd -.RB [ \-\-debug \] -.RB [ \-\-udev \] -.ad b -. -.SH DESCRIPTION -. -lvmdbusd is a service which provides a D-Bus API to the logical volume manager (LVM). -Run -.BR lvmdbusd (8) -as root. -. -.SH OPTIONS -. -.HP -.BR \-\-debug -.br -Enable debug statements -. -.HP -.BR \-\-udev -.br -Use udev events to trigger updates -. -.SH SEE ALSO -. -.nh -.BR dbus-send (1), -.BR lvm (8) diff --git a/man/lvmdbusd.8_main b/man/lvmdbusd.8_main new file mode 100644 index 0000000..9e035f5 --- /dev/null +++ b/man/lvmdbusd.8_main @@ -0,0 +1,38 @@ +.TH LVMDBUSD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- +. +.SH NAME +. +lvmdbusd \(em LVM D-Bus daemon +. +.SH SYNOPSIS +. +.ad l +.B lvmdbusd +.RB [ \-\-debug \] +.RB [ \-\-udev \] +.ad b +. +.SH DESCRIPTION +. +lvmdbusd is a service which provides a D-Bus API to the logical volume manager (LVM). +Run +.BR lvmdbusd (8) +as root. +. +.SH OPTIONS +. +.HP +.BR \-\-debug +.br +Enable debug statements +. +.HP +.BR \-\-udev +.br +Use udev events to trigger updates +. +.SH SEE ALSO +. +.nh +.BR dbus-send (1), +.BR lvm (8) diff --git a/man/lvmdiskscan.8.des b/man/lvmdiskscan.8.des deleted file mode 100644 index c1e87cc..0000000 --- a/man/lvmdiskscan.8.des +++ /dev/null @@ -1,7 +0,0 @@ -lvmdiskscan scans all SCSI, (E)IDE disks, multiple devices and a bunch of -other block devices in the system looking for LVM PVs. The size reported -is the real device size. Define a filter in \fBlvm.conf\fP(5) to restrict -the scan to avoid a CD ROM, for example. - -This command is deprecated, use \fBpvs\fP instead. - diff --git a/man/lvmdiskscan.8_des b/man/lvmdiskscan.8_des new file mode 100644 index 0000000..c1e87cc --- /dev/null +++ b/man/lvmdiskscan.8_des @@ -0,0 +1,7 @@ +lvmdiskscan scans all SCSI, (E)IDE disks, multiple devices and a bunch of +other block devices in the system looking for LVM PVs. The size reported +is the real device size. Define a filter in \fBlvm.conf\fP(5) to restrict +the scan to avoid a CD ROM, for example. + +This command is deprecated, use \fBpvs\fP instead. + diff --git a/man/lvmdiskscan.8_end b/man/lvmdiskscan.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvmdiskscan.8_pregen b/man/lvmdiskscan.8_pregen new file mode 100644 index 0000000..fc87d65 --- /dev/null +++ b/man/lvmdiskscan.8_pregen @@ -0,0 +1,314 @@ +.TH LVMDISKSCAN 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvmdiskscan \- List devices that may be used as physical volumes +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvmdiskscan\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +lvmdiskscan scans all SCSI, (E)IDE disks, multiple devices and a bunch of +other block devices in the system looking for LVM PVs. The size reported +is the real device size. Define a filter in \fBlvm.conf\fP(5) to restrict +the scan to avoid a CD ROM, for example. + +This command is deprecated, use \fBpvs\fP instead. + + +.P +.SH USAGE +.br +.P +. +\fBlvmdiskscan\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--lvmpartition\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--lvmpartition\fP +.br +Only report PVs. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvmdump.8.in b/man/lvmdump.8.in deleted file mode 100644 index d0e102e..0000000 --- a/man/lvmdump.8.in +++ /dev/null @@ -1,112 +0,0 @@ -.TH LVMDUMP 8 "LVM TOOLS #VERSION#" "Red Hat, Inc." -.SH NAME -lvmdump \(em create lvm2 information dumps for diagnostic purposes -.SH SYNOPSIS -.B lvmdump -.RB [ \-a ] -.RB [ \-c ] -.RB [ \-d -.IR directory ] -.RB [ \-h ] -.RB [ \-l ] -.RB [ \-m ] -.RB [ \-p ] -.RB [ \-s ] -.RB [ \-u ] -.SH DESCRIPTION -lvmdump is a tool to dump various information concerning LVM2. -By default, it creates a tarball suitable for submission along -with a problem report. -.PP -The content of the tarball is as follows: -.br -- dmsetup info -.br -- table of currently running processes -.br -- recent entries from /var/log/messages (containing system messages) -.br -- complete lvm configuration and cache (content of /etc/lvm) -.br -- list of device nodes present under /dev -.br -- list of files present /sys/block -.br -- list of files present /sys/devices/virtual/block -.br -- if enabled with \-m, metadata dump will be also included -.br -- if enabled with \-a, debug output of vgscan, pvscan and list of all available volume groups, physical volumes and logical volumes will be included -.br -- if enabled with \-c, cluster status info -.br -- if enabled with \-l, lvmetad state if running -.br -- if enabled with \-p, lvmpolld state if running -.br -- if enabled with \-s, system info and context -.br -- if enabled with \-u, udev info and context -.SH OPTIONS -.TP -.B \-a -Advanced collection. -\fBWARNING\fR: if lvm is already hung, then this script may hang as well -if \fB\-a\fR is used. -.TP -.B \-c -If clvmd is running, gather cluster data as well. -.TP -.B \-d \fIdirectory -Dump into a directory instead of tarball -By default, lvmdump will produce a single compressed tarball containing -all the information. Using this option, it can be instructed to only -produce the raw dump tree, rooted in \fIdirectory\fP. -.TP -.B \-h -Print help message -.TP -.B \-l -Include \fBlvmetad\fP(8) daemon dump if it is running. The dump contains -cached information that is currently stored in lvmetad: VG metadata, -PV metadata and various mappings in between these metadata for quick -access. -.TP -.B \-m -Gather LVM metadata from the PVs -This option generates a 1:1 dump of the metadata area from all PVs visible -to the system, which can cause the dump to increase in size considerably. -However, the metadata dump may represent a valuable diagnostic resource. -.TP -.B \-p -Include \fBlvmpolld\fP(8) daemon dump if it is running. The dump contains -all in-progress operation currently monitored by the daemon and partial -history for all yet uncollected results of polling operations already finished -including reason. -.TP -.B \-s -Gather system info and context. Currently, this encompasses info gathered -by calling lsblk command and various systemd info and context: overall state -of systemd units present in the system, more detailed status of units -controlling LVM functionality and the content of systemd journal for -current boot. -.TP -.B \-u -Gather udev info and context: /etc/udev/udev.conf file, udev daemon version -(output of 'udevadm info \-\-version' command), udev rules currently used in the system -(content of /lib/udev/rules.d and /etc/udev/rules.d directory), -list of files in /lib/udev directory and dump of current udev -database content (the output of 'udevadm info \-\-export\-db' command). -.SH ENVIRONMENT VARIABLES -.TP -\fBLVM_BINARY\fP -The LVM2 binary to use. -Defaults to "lvm". -Sometimes you might need to set this to "/sbin/lvm.static", for example. -.TP -\fBDMSETUP_BINARY\fP -The dmsetup binary to use. -Defaults to "dmsetup". -.PP -.SH SEE ALSO -.BR lvm (8) diff --git a/man/lvmdump.8_main b/man/lvmdump.8_main new file mode 100644 index 0000000..d0e102e --- /dev/null +++ b/man/lvmdump.8_main @@ -0,0 +1,112 @@ +.TH LVMDUMP 8 "LVM TOOLS #VERSION#" "Red Hat, Inc." +.SH NAME +lvmdump \(em create lvm2 information dumps for diagnostic purposes +.SH SYNOPSIS +.B lvmdump +.RB [ \-a ] +.RB [ \-c ] +.RB [ \-d +.IR directory ] +.RB [ \-h ] +.RB [ \-l ] +.RB [ \-m ] +.RB [ \-p ] +.RB [ \-s ] +.RB [ \-u ] +.SH DESCRIPTION +lvmdump is a tool to dump various information concerning LVM2. +By default, it creates a tarball suitable for submission along +with a problem report. +.PP +The content of the tarball is as follows: +.br +- dmsetup info +.br +- table of currently running processes +.br +- recent entries from /var/log/messages (containing system messages) +.br +- complete lvm configuration and cache (content of /etc/lvm) +.br +- list of device nodes present under /dev +.br +- list of files present /sys/block +.br +- list of files present /sys/devices/virtual/block +.br +- if enabled with \-m, metadata dump will be also included +.br +- if enabled with \-a, debug output of vgscan, pvscan and list of all available volume groups, physical volumes and logical volumes will be included +.br +- if enabled with \-c, cluster status info +.br +- if enabled with \-l, lvmetad state if running +.br +- if enabled with \-p, lvmpolld state if running +.br +- if enabled with \-s, system info and context +.br +- if enabled with \-u, udev info and context +.SH OPTIONS +.TP +.B \-a +Advanced collection. +\fBWARNING\fR: if lvm is already hung, then this script may hang as well +if \fB\-a\fR is used. +.TP +.B \-c +If clvmd is running, gather cluster data as well. +.TP +.B \-d \fIdirectory +Dump into a directory instead of tarball +By default, lvmdump will produce a single compressed tarball containing +all the information. Using this option, it can be instructed to only +produce the raw dump tree, rooted in \fIdirectory\fP. +.TP +.B \-h +Print help message +.TP +.B \-l +Include \fBlvmetad\fP(8) daemon dump if it is running. The dump contains +cached information that is currently stored in lvmetad: VG metadata, +PV metadata and various mappings in between these metadata for quick +access. +.TP +.B \-m +Gather LVM metadata from the PVs +This option generates a 1:1 dump of the metadata area from all PVs visible +to the system, which can cause the dump to increase in size considerably. +However, the metadata dump may represent a valuable diagnostic resource. +.TP +.B \-p +Include \fBlvmpolld\fP(8) daemon dump if it is running. The dump contains +all in-progress operation currently monitored by the daemon and partial +history for all yet uncollected results of polling operations already finished +including reason. +.TP +.B \-s +Gather system info and context. Currently, this encompasses info gathered +by calling lsblk command and various systemd info and context: overall state +of systemd units present in the system, more detailed status of units +controlling LVM functionality and the content of systemd journal for +current boot. +.TP +.B \-u +Gather udev info and context: /etc/udev/udev.conf file, udev daemon version +(output of 'udevadm info \-\-version' command), udev rules currently used in the system +(content of /lib/udev/rules.d and /etc/udev/rules.d directory), +list of files in /lib/udev directory and dump of current udev +database content (the output of 'udevadm info \-\-export\-db' command). +.SH ENVIRONMENT VARIABLES +.TP +\fBLVM_BINARY\fP +The LVM2 binary to use. +Defaults to "lvm". +Sometimes you might need to set this to "/sbin/lvm.static", for example. +.TP +\fBDMSETUP_BINARY\fP +The dmsetup binary to use. +Defaults to "dmsetup". +.PP +.SH SEE ALSO +.BR lvm (8) diff --git a/man/lvmetad.8.in b/man/lvmetad.8.in deleted file mode 100644 index c665e18..0000000 --- a/man/lvmetad.8.in +++ /dev/null @@ -1,126 +0,0 @@ -.TH LVMETAD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- -.SH NAME -lvmetad \(em LVM metadata cache daemon - -.SH SYNOPSIS -.B lvmetad -.RB [ \-l -.IR level [,level...]] -.RB [ \-p -.IR pidfile_path ] -.RB [ \-s -.IR socket_path ] -.RB [ \-t -.IR timeout_value ] -.RB [ \-f ] -.RB [ \-h ] -.RB [ \-V ] -.RB [ \-? ] - -.SH DESCRIPTION - -The lvmetad daemon caches LVM metadata so that LVM commands can read -metadata from the cache rather than scanning disks. This can be an -advantage because scanning disks is time consuming and may interfere with -the normal work of the system. lvmetad can be a disadvantage when disk -event notifications from the system are unreliable. - -lvmetad does not read metadata from disks itself. Instead, it relies on -an LVM command, like pvscan \-\-cache, to read metadata from disks and -send it to lvmetad to be cached. - -New LVM disks that appear on the system must be scanned before lvmetad -knows about them. If lvmetad does not know about a disk, then LVM -commands using lvmetad will also not know about it. When disks are added -or removed from the system, lvmetad must be updated. - -lvmetad is usually combined with event\-based system services that -automatically run pvscan \-\-cache on disks added or removed. This way, -the cache is automatically updated with metadata from new disks when they -appear. LVM udev rules and systemd services implement this automation. -Automatic scanning is usually combined with automatic activation. For -more information, see -.BR pvscan (8). - -If lvmetad is started or restarted after disks have been added to the -system, or if the global_filter has changed, the cache must be updated. -This can be done by running pvscan \-\-cache, or it will be done -automatically by the next LVM command that's run. - -When lvmetad is not used, LVM commands revert to scanning disks for LVM -metadata. - -In some cases, lvmetad will be temporarily disabled while it continues -running. In this state, LVM commands will ignore the lvmetad cache and -revert to scanning disks. A warning will also be printed which includes -the reason why lvmetad is not being used. The most common reason is the -existence of duplicate PVs (lvmetad cannot cache data for duplicate PVs.) -Once duplicates have been resolved, the lvmetad cache is can be updated -with pvscan \-\-cache and commands will return to using the cache. - -Use of lvmetad is enabled/disabled by: -.br -.BR lvm.conf (5) -.B global/use_lvmetad - -For more information on this setting, see: -.br -.B lvmconfig \-\-withcomments global/use_lvmetad - -To ignore disks from LVM at the system level, e.g. lvmetad, pvscan use: -.br -.BR lvm.conf (5) -.B devices/global_filter - -For more information on this setting, see -.br -.B lvmconfig \-\-withcomments devices/global_filter - -.SH OPTIONS - -To run the daemon in a test environment both the pidfile_path and the -socket_path should be changed from the defaults. -.TP -.B \-f -Don't fork, but run in the foreground. -.TP -.BR \-h ", " \-? -Show help information. -.TP -.B \-l \fIlevels -Specify the levels of log messages to generate as a comma separated list. -Messages are logged by syslog. -Additionally, when \-f is given they are also sent to standard error. -Possible levels are: all, fatal, error, warn, info, wire, debug. -.TP -.B \-p \fIpidfile_path -Path to the pidfile. This overrides both the built-in default -(#DEFAULT_PID_DIR#/lvmetad.pid) and the environment variable -\fBLVM_LVMETAD_PIDFILE\fP. This file is used to prevent more -than one instance of the daemon running simultaneously. -.TP -.B \-s \fIsocket_path -Path to the socket file. This overrides both the built-in default -(#DEFAULT_RUN_DIR#/lvmetad.socket) and the environment variable -\fBLVM_LVMETAD_SOCKET\fP. To communicate successfully with lvmetad, -all LVM2 processes should use the same socket path. -.TP -.B \-t \fItimeout_value -The daemon may shutdown after being idle for the given time (in seconds). When the -option is omitted or the value given is zero the daemon never shutdowns on idle. -.TP -.B \-V -Display the version of lvmetad daemon. -.SH ENVIRONMENT VARIABLES -.TP -.B LVM_LVMETAD_PIDFILE -Path for the pid file. -.TP -.B LVM_LVMETAD_SOCKET -Path for the socket file. - -.SH SEE ALSO -.BR lvm (8), -.BR lvmconfig (8), -.BR lvm.conf (5), -.BR pvscan (8) diff --git a/man/lvmetad.8_main b/man/lvmetad.8_main new file mode 100644 index 0000000..c665e18 --- /dev/null +++ b/man/lvmetad.8_main @@ -0,0 +1,126 @@ +.TH LVMETAD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- +.SH NAME +lvmetad \(em LVM metadata cache daemon + +.SH SYNOPSIS +.B lvmetad +.RB [ \-l +.IR level [,level...]] +.RB [ \-p +.IR pidfile_path ] +.RB [ \-s +.IR socket_path ] +.RB [ \-t +.IR timeout_value ] +.RB [ \-f ] +.RB [ \-h ] +.RB [ \-V ] +.RB [ \-? ] + +.SH DESCRIPTION + +The lvmetad daemon caches LVM metadata so that LVM commands can read +metadata from the cache rather than scanning disks. This can be an +advantage because scanning disks is time consuming and may interfere with +the normal work of the system. lvmetad can be a disadvantage when disk +event notifications from the system are unreliable. + +lvmetad does not read metadata from disks itself. Instead, it relies on +an LVM command, like pvscan \-\-cache, to read metadata from disks and +send it to lvmetad to be cached. + +New LVM disks that appear on the system must be scanned before lvmetad +knows about them. If lvmetad does not know about a disk, then LVM +commands using lvmetad will also not know about it. When disks are added +or removed from the system, lvmetad must be updated. + +lvmetad is usually combined with event\-based system services that +automatically run pvscan \-\-cache on disks added or removed. This way, +the cache is automatically updated with metadata from new disks when they +appear. LVM udev rules and systemd services implement this automation. +Automatic scanning is usually combined with automatic activation. For +more information, see +.BR pvscan (8). + +If lvmetad is started or restarted after disks have been added to the +system, or if the global_filter has changed, the cache must be updated. +This can be done by running pvscan \-\-cache, or it will be done +automatically by the next LVM command that's run. + +When lvmetad is not used, LVM commands revert to scanning disks for LVM +metadata. + +In some cases, lvmetad will be temporarily disabled while it continues +running. In this state, LVM commands will ignore the lvmetad cache and +revert to scanning disks. A warning will also be printed which includes +the reason why lvmetad is not being used. The most common reason is the +existence of duplicate PVs (lvmetad cannot cache data for duplicate PVs.) +Once duplicates have been resolved, the lvmetad cache is can be updated +with pvscan \-\-cache and commands will return to using the cache. + +Use of lvmetad is enabled/disabled by: +.br +.BR lvm.conf (5) +.B global/use_lvmetad + +For more information on this setting, see: +.br +.B lvmconfig \-\-withcomments global/use_lvmetad + +To ignore disks from LVM at the system level, e.g. lvmetad, pvscan use: +.br +.BR lvm.conf (5) +.B devices/global_filter + +For more information on this setting, see +.br +.B lvmconfig \-\-withcomments devices/global_filter + +.SH OPTIONS + +To run the daemon in a test environment both the pidfile_path and the +socket_path should be changed from the defaults. +.TP +.B \-f +Don't fork, but run in the foreground. +.TP +.BR \-h ", " \-? +Show help information. +.TP +.B \-l \fIlevels +Specify the levels of log messages to generate as a comma separated list. +Messages are logged by syslog. +Additionally, when \-f is given they are also sent to standard error. +Possible levels are: all, fatal, error, warn, info, wire, debug. +.TP +.B \-p \fIpidfile_path +Path to the pidfile. This overrides both the built-in default +(#DEFAULT_PID_DIR#/lvmetad.pid) and the environment variable +\fBLVM_LVMETAD_PIDFILE\fP. This file is used to prevent more +than one instance of the daemon running simultaneously. +.TP +.B \-s \fIsocket_path +Path to the socket file. This overrides both the built-in default +(#DEFAULT_RUN_DIR#/lvmetad.socket) and the environment variable +\fBLVM_LVMETAD_SOCKET\fP. To communicate successfully with lvmetad, +all LVM2 processes should use the same socket path. +.TP +.B \-t \fItimeout_value +The daemon may shutdown after being idle for the given time (in seconds). When the +option is omitted or the value given is zero the daemon never shutdowns on idle. +.TP +.B \-V +Display the version of lvmetad daemon. +.SH ENVIRONMENT VARIABLES +.TP +.B LVM_LVMETAD_PIDFILE +Path for the pid file. +.TP +.B LVM_LVMETAD_SOCKET +Path for the socket file. + +.SH SEE ALSO +.BR lvm (8), +.BR lvmconfig (8), +.BR lvm.conf (5), +.BR pvscan (8) diff --git a/man/lvmlockctl.8.in b/man/lvmlockctl.8.in deleted file mode 100644 index 5465642..0000000 --- a/man/lvmlockctl.8.in +++ /dev/null @@ -1,102 +0,0 @@ -.TH "LVMLOCKCTL" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" - -.SH NAME -lvmlockctl \(em Control for lvmlockd - -.SH DESCRIPTION -This command interacts with -.BR lvmlockd (8). - -.SH OPTIONS - -lvmlockctl [options] - -.B \-\-help | \-h - Show this help information. - -.B \-\-quit | \-q - Tell lvmlockd to quit. - -.B \-\-info | \-i - Print lock state information from lvmlockd. - -.B \-\-dump | \-d - Print log buffer from lvmlockd. - -.B \-\-wait | \-w 0|1 - Wait option for other commands. - -.B \-\-force | \-f 0|1 - Force option for other commands. - -.B \-\-kill | \-k -.I vgname - Kill access to the VG when sanlock cannot renew lease. - -.B \-\-drop | \-r -.I vgname - Clear locks for the VG when it is unused after kill (-k). - -.B \-\-gl\-enable | \-E -.I vgname - Tell lvmlockd to enable the global lock in a sanlock VG. - -.B \-\-gl\-disable | \-D -.I vgname - Tell lvmlockd to disable the global lock in a sanlock VG. - -.B \-\-stop\-lockspaces | \-S - Stop all lockspaces. - - -.SH USAGE - -.SS info - -This collects and displays lock state from lvmlockd. The display is -primitive, incomplete and will change in future version. To print the raw -lock state from lvmlockd, combine this option with --dump|-d. - -.SS dump - -This collects the circular log buffer of debug statements from lvmlockd -and prints it. - -.SS kill - -This is run by sanlock when it loses access to the storage holding leases -for a VG. It currently emits a syslog message stating that the VG must -be immediately deactivated. In the future it may automatically attempt to -forcibly deactivate the VG. For more, see -.BR lvmlockd (8). - -.SS drop - -This should only be run after a VG has been successfully deactivated -following an lvmlockctl \-\-kill command. It clears the stale lockspace -from lvmlockd. In the future, this may become automatic along with an -automatic handling of \-\-kill. For more, see -.BR lvmlockd (8). - -.SS gl\-enable - -This enables the global lock in a sanlock VG. This is necessary if the VG -that previously held the global lock is removed. For more, see -.BR lvmlockd (8). - -.SS gl\-disable - -This disables the global lock in a sanlock VG. This is necessary if the -global lock has mistakenly been enabled in more than one VG. The global -lock should be disabled in all but one sanlock VG. For more, see -.BR lvmlockd (8). - -.SS stop\-lockspaces - -This tells lvmlockd to stop all lockspaces. It can be useful to stop -lockspaces for VGs that the vgchange \-\-lock\-stop comand can no longer -see, or to stop the dlm global lockspace which is not directly stopped by -the vgchange command. The wait and force options can be used with this -command. - - diff --git a/man/lvmlockctl.8_main b/man/lvmlockctl.8_main new file mode 100644 index 0000000..5465642 --- /dev/null +++ b/man/lvmlockctl.8_main @@ -0,0 +1,102 @@ +.TH "LVMLOCKCTL" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" + +.SH NAME +lvmlockctl \(em Control for lvmlockd + +.SH DESCRIPTION +This command interacts with +.BR lvmlockd (8). + +.SH OPTIONS + +lvmlockctl [options] + +.B \-\-help | \-h + Show this help information. + +.B \-\-quit | \-q + Tell lvmlockd to quit. + +.B \-\-info | \-i + Print lock state information from lvmlockd. + +.B \-\-dump | \-d + Print log buffer from lvmlockd. + +.B \-\-wait | \-w 0|1 + Wait option for other commands. + +.B \-\-force | \-f 0|1 + Force option for other commands. + +.B \-\-kill | \-k +.I vgname + Kill access to the VG when sanlock cannot renew lease. + +.B \-\-drop | \-r +.I vgname + Clear locks for the VG when it is unused after kill (-k). + +.B \-\-gl\-enable | \-E +.I vgname + Tell lvmlockd to enable the global lock in a sanlock VG. + +.B \-\-gl\-disable | \-D +.I vgname + Tell lvmlockd to disable the global lock in a sanlock VG. + +.B \-\-stop\-lockspaces | \-S + Stop all lockspaces. + + +.SH USAGE + +.SS info + +This collects and displays lock state from lvmlockd. The display is +primitive, incomplete and will change in future version. To print the raw +lock state from lvmlockd, combine this option with --dump|-d. + +.SS dump + +This collects the circular log buffer of debug statements from lvmlockd +and prints it. + +.SS kill + +This is run by sanlock when it loses access to the storage holding leases +for a VG. It currently emits a syslog message stating that the VG must +be immediately deactivated. In the future it may automatically attempt to +forcibly deactivate the VG. For more, see +.BR lvmlockd (8). + +.SS drop + +This should only be run after a VG has been successfully deactivated +following an lvmlockctl \-\-kill command. It clears the stale lockspace +from lvmlockd. In the future, this may become automatic along with an +automatic handling of \-\-kill. For more, see +.BR lvmlockd (8). + +.SS gl\-enable + +This enables the global lock in a sanlock VG. This is necessary if the VG +that previously held the global lock is removed. For more, see +.BR lvmlockd (8). + +.SS gl\-disable + +This disables the global lock in a sanlock VG. This is necessary if the +global lock has mistakenly been enabled in more than one VG. The global +lock should be disabled in all but one sanlock VG. For more, see +.BR lvmlockd (8). + +.SS stop\-lockspaces + +This tells lvmlockd to stop all lockspaces. It can be useful to stop +lockspaces for VGs that the vgchange \-\-lock\-stop comand can no longer +see, or to stop the dlm global lockspace which is not directly stopped by +the vgchange command. The wait and force options can be used with this +command. + + diff --git a/man/lvmlockd.8.in b/man/lvmlockd.8.in deleted file mode 100644 index 6e9b703..0000000 --- a/man/lvmlockd.8.in +++ /dev/null @@ -1,889 +0,0 @@ -.TH "LVMLOCKD" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" - -.SH NAME -lvmlockd \(em LVM locking daemon - -.SH DESCRIPTION -LVM commands use lvmlockd to coordinate access to shared storage. -.br -When LVM is used on devices shared by multiple hosts, locks will: - -\[bu] -coordinate reading and writing of LVM metadata -.br -\[bu] -validate caching of LVM metadata -.br -\[bu] -prevent concurrent activation of logical volumes -.br - -lvmlockd uses an external lock manager to perform basic locking. -.br -Lock manager (lock type) options are: - -\[bu] -sanlock: places locks on disk within LVM storage. -.br -\[bu] -dlm: uses network communication and a cluster manager. -.br - -.SH OPTIONS - -lvmlockd [options] - -For default settings, see lvmlockd \-h. - -.B \-\-help | \-h - Show this help information. - -.B \-\-version | \-V - Show version of lvmlockd. - -.B \-\-test | \-T - Test mode, do not call lock manager. - -.B \-\-foreground | \-f - Don't fork. - -.B \-\-daemon\-debug | \-D - Don't fork and print debugging to stdout. - -.B \-\-pid\-file | \-p -.I path - Set path to the pid file. - -.B \-\-socket\-path | \-s -.I path - Set path to the socket to listen on. - -.B \-\-syslog\-priority | \-S err|warning|debug - Write log messages from this level up to syslog. - -.B \-\-gl\-type | \-g sanlock|dlm - Set global lock type to be sanlock or dlm. - -.B \-\-host\-id | \-i -.I num - Set the local sanlock host id. - -.B \-\-host\-id\-file | \-F -.I path - A file containing the local sanlock host_id. - -.B \-\-sanlock\-timeout | \-o -.I seconds - Override the default sanlock I/O timeout. - -.B \-\-adopt | \-A 0|1 - Adopt locks from a previous instance of lvmlockd. - - -.SH USAGE - -.SS Initial set up - -Using LVM with lvmlockd for the first time includes some one\-time set up -steps: - -.SS 1. choose a lock manager - -.I dlm -.br -If dlm (or corosync) are already being used by other cluster -software, then select dlm. dlm uses corosync which requires additional -configuration beyond the scope of this document. See corosync and dlm -documentation for instructions on configuration, setup and usage. - -.I sanlock -.br -Choose sanlock if dlm/corosync are not otherwise required. -sanlock does not depend on any clustering software or configuration. - -.SS 2. configure hosts to use lvmlockd - -On all hosts running lvmlockd, configure lvm.conf: -.nf -locking_type = 1 -use_lvmlockd = 1 -.fi - -.I sanlock -.br -Assign each host a unique host_id in the range 1\-2000 by setting -.br -/etc/lvm/lvmlocal.conf local/host_id - -.SS 3. start lvmlockd - -Use a service/init file if available, or just run "lvmlockd". - -.SS 4. start lock manager - -.I sanlock -.br -systemctl start wdmd sanlock - -.I dlm -.br -Follow external clustering documentation when applicable, otherwise: -.br -systemctl start corosync dlm - -.SS 5. create VG on shared devices - -vgcreate \-\-shared - -The shared option sets the VG lock type to sanlock or dlm depending on -which lock manager is running. LVM commands will perform locking for the -VG using lvmlockd. lvmlockd will use the chosen lock manager. - -.SS 6. start VG on all hosts - -vgchange \-\-lock\-start - -lvmlockd requires shared VGs to be started before they are used. This is -a lock manager operation to start (join) the VG lockspace, and it may take -some time. Until the start completes, locks for the VG are not available. -LVM commands are allowed to read the VG while start is in progress. (An -init/unit file can also be used to start VGs.) - -.SS 7. create and activate LVs - -Standard lvcreate and lvchange commands are used to create and activate -LVs in a shared VG. - -An LV activated exclusively on one host cannot be activated on another. -When multiple hosts need to use the same LV concurrently, the LV can be -activated with a shared lock (see lvchange options \-aey vs \-asy.) -(Shared locks are disallowed for certain LV types that cannot be used from -multiple hosts.) - - -.SS Normal start up and shut down - -After initial set up, start up and shut down include the following general -steps. They can be performed manually or using the system service -manager. - -\[bu] -start lvmetad -.br -\[bu] -start lvmlockd -.br -\[bu] -start lock manager -.br -\[bu] -vgchange \-\-lock\-start -.br -\[bu] -activate LVs in shared VGs -.br - -The shut down sequence is the reverse: - -\[bu] -deactivate LVs in shared VGs -.br -\[bu] -vgchange \-\-lock\-stop -.br -\[bu] -stop lock manager -.br -\[bu] -stop lvmlockd -.br -\[bu] -stop lvmetad -.br - -.P - -.SH TOPICS - -.SS VG access control - -The following terms are used to describe different forms of VG access -control. - -.I "lockd VG" - -A "lockd VG" is a shared VG that has a "lock type" of dlm or sanlock. -Using it requires lvmlockd. These VGs exist on shared storage that is -visible to multiple hosts. LVM commands use lvmlockd to perform locking -for these VGs when they are used. - -If the lock manager for the lock type is not available (e.g. not started -or failed), lvmlockd is unable to acquire locks for LVM commands. LVM -commands that only read the VG will generally be allowed to continue -without locks in this case (with a warning). Commands to modify or -activate the VG will fail without the necessary locks. - -.I "local VG" - -A "local VG" is meant to be used by a single host. It has no lock type or -lock type "none". LVM commands and lvmlockd do not perform locking for -these VGs. A local VG typically exists on local (non\-shared) devices and -cannot be used concurrently from different hosts. - -If a local VG does exist on shared devices, it should be owned by a single -host by having its system ID set, see -.BR lvmsystemid (7). -Only the host with a matching system ID can use the local VG. A VG -with no lock type and no system ID should be excluded from all but one -host using lvm.conf filters. Without any of these protections, a local VG -on shared devices can be easily damaged or destroyed. - -.I "clvm VG" - -A "clvm VG" is a VG on shared storage (like a lockd VG) that requires -clvmd for clustering. See below for converting a clvm VG to a lockd VG. - - -.SS lockd VGs from hosts not using lvmlockd - -Only hosts that use lockd VGs should be configured to run lvmlockd. -However, shared devices used by lockd VGs may be visible from hosts not -using lvmlockd. From a host not using lvmlockd, visible lockd VGs are -ignored in the same way as foreign VGs (see -.BR lvmsystemid (7).) - -The \-\-shared option for reporting and display commands causes lockd VGs -to be displayed on a host not using lvmlockd, like the \-\-foreign option -does for foreign VGs. - - -.SS vgcreate comparison - -The type of VG access control is specified in the vgcreate command. -See -.BR vgcreate (8) -for all vgcreate options. - -.B vgcreate - -.IP \[bu] 2 -Creates a local VG with the local system ID when neither lvmlockd nor clvm are configured. -.IP \[bu] 2 -Creates a local VG with the local system ID when lvmlockd is configured. -.IP \[bu] 2 -Creates a clvm VG when clvm is configured. - -.P - -.B vgcreate \-\-shared -.IP \[bu] 2 -Requires lvmlockd to be configured and running. -.IP \[bu] 2 -Creates a lockd VG with lock type sanlock|dlm depending on which lock -manager is running. -.IP \[bu] 2 -LVM commands request locks from lvmlockd to use the VG. -.IP \[bu] 2 -lvmlockd obtains locks from the selected lock manager. - -.P - -.B vgcreate \-c|\-\-clustered y -.IP \[bu] 2 -Requires clvm to be configured and running. -.IP \[bu] 2 -Creates a clvm VG with the "clustered" flag. -.IP \[bu] 2 -LVM commands request locks from clvmd to use the VG. - -.P - -.SS creating the first sanlock VG - -Creating the first sanlock VG is not protected by locking and requires -special attention. This is because sanlock locks exist within the VG, so -they are not available until the VG exists. The first sanlock VG will -contain the "global lock". - -.IP \[bu] 2 -The first vgcreate command needs to be given the path to a device that has -not yet been initialized with pvcreate. The pvcreate initialization will -be done by vgcreate. This is because the pvcreate command requires the -global lock, which will not be available until after the first sanlock VG -is created. - -.IP \[bu] 2 -While running vgcreate for the first sanlock VG, ensure that the device -being used is not used by another LVM command. Allocation of shared -devices is usually protected by the global lock, but this cannot be done -for the first sanlock VG which will hold the global lock. - -.IP \[bu] 2 -While running vgcreate for the first sanlock VG, ensure that the VG name -being used is not used by another LVM command. Uniqueness of VG names is -usually ensured by the global lock. - -.IP \[bu] 2 -Because the first sanlock VG will contain the global lock, this VG needs -to be accessible to all hosts that will use sanlock shared VGs. All hosts -will need to use the global lock from the first sanlock VG. - -See below for more information about managing the sanlock global lock. - - -.SS using lockd VGs - -There are some special considerations when using lockd VGs. - -When use_lvmlockd is first enabled in lvm.conf, and before the first lockd -VG is created, no global lock will exist. In this initial state, LVM -commands try and fail to acquire the global lock, producing a warning, and -some commands are disallowed. Once the first lockd VG is created, the -global lock will be available, and LVM will be fully operational. - -When a new lockd VG is created, its lockspace is automatically started on -the host that creates it. Other hosts need to run 'vgchange -\-\-lock\-start' to start the new VG before they can use it. - -From the 'vgs' command, lockd VGs are indicated by "s" (for shared) in the -sixth attr field. The specific lock type and lock args for a lockd VG can -be displayed with 'vgs \-o+locktype,lockargs'. - -lockd VGs need to be "started" and "stopped", unlike other types of VGs. -See the following section for a full description of starting and stopping. - -vgremove of a lockd VG will fail if other hosts have the VG started. -Run vgchange \-\-lock-stop on all other hosts before vgremove. -(It may take several seconds before vgremove recognizes that all hosts -have stopped a sanlock VG.) - -.SS starting and stopping VGs - -Starting a lockd VG (vgchange \-\-lock\-start) causes the lock manager to -start (join) the lockspace for the VG on the host where it is run. This -makes locks for the VG available to LVM commands on the host. Before a VG -is started, only LVM commands that read/display the VG are allowed to -continue without locks (and with a warning). - -Stopping a lockd VG (vgchange \-\-lock\-stop) causes the lock manager to -stop (leave) the lockspace for the VG on the host where it is run. This -makes locks for the VG inaccessible to the host. A VG cannot be stopped -while it has active LVs. - -When using the lock type sanlock, starting a VG can take a long time -(potentially minutes if the host was previously shut down without cleanly -stopping the VG.) - -A lockd VG can be started after all the following are true: -.br -\[bu] -lvmlockd is running -.br -\[bu] -the lock manager is running -.br -\[bu] -the VG is visible to the system -.br - -A lockd VG can be stopped if all LVs are deactivated. - -All lockd VGs can be started/stopped using: -.br -vgchange \-\-lock-start -.br -vgchange \-\-lock-stop - - -Individual VGs can be started/stopped using: -.br -vgchange \-\-lock\-start ... -.br -vgchange \-\-lock\-stop ... - -To make vgchange not wait for start to complete: -.br -vgchange \-\-lock\-start \-\-lock\-opt nowait ... - -lvmlockd can be asked directly to stop all lockspaces: -.br -lvmlockctl \-\-stop\-lockspaces - -To start only selected lockd VGs, use the lvm.conf -activation/lock_start_list. When defined, only VG names in this list are -started by vgchange. If the list is not defined (the default), all -visible lockd VGs are started. To start only "vg1", use the following -lvm.conf configuration: - -.nf -activation { - lock_start_list = [ "vg1" ] - ... -} -.fi - - -.SS automatic starting and automatic activation - -Scripts or programs on a host that automatically start VGs will use the -"auto" option to indicate that the command is being run automatically by -the system: - -vgchange \-\-lock\-start \-\-lock\-opt auto [ ...] - -Without any additional configuration, including the "auto" option has no -effect; all VGs are started unless restricted by lock_start_list. - -However, when the lvm.conf activation/auto_lock_start_list is defined, the -auto start command performs an additional filtering phase to all VGs being -started, testing each VG name against the auto_lock_start_list. The -auto_lock_start_list defines lockd VGs that will be started by the auto -start command. Visible lockd VGs not included in the list are ignored by -the auto start command. If the list is undefined, all VG names pass this -filter. (The lock_start_list is also still used to filter all VGs.) - -The auto_lock_start_list allows a user to select certain lockd VGs that -should be automatically started by the system (or indirectly, those that -should not). - -To use auto activation of lockd LVs (see auto_activation_volume_list), -auto starting of the corresponding lockd VGs is necessary. - - -.SS internal command locking - -To optimize the use of LVM with lvmlockd, be aware of the three kinds of -locks and when they are used: - -.I GL lock - -The global lock (GL lock) is associated with global information, which is -information not isolated to a single VG. This includes: - -\[bu] -The global VG namespace. -.br -\[bu] -The set of orphan PVs and unused devices. -.br -\[bu] -The properties of orphan PVs, e.g. PV size. -.br - -The global lock is used in shared mode by commands that read this -information, or in exclusive mode by commands that change it. - -The command 'vgs' acquires the global lock in shared mode because it -reports the list of all VG names. - -The vgcreate command acquires the global lock in exclusive mode because it -creates a new VG name, and it takes a PV from the list of unused PVs. - -When an LVM command is given a tag argument, or uses select, it must read -all VGs to match the tag or selection, which causes the global lock to be -acquired. - -.I VG lock - -A VG lock is associated with each VG. The VG lock is acquired in shared -mode to read the VG and in exclusive mode to change the VG (modify the VG -metadata or activate LVs). This lock serializes access to a VG with all -other LVM commands accessing the VG from all hosts. - -The command 'vgs' will not only acquire the GL lock to read the list of -all VG names, but will acquire the VG lock for each VG prior to reading -it. - -The command 'vgs ' does not acquire the GL lock (it does not need -the list of all VG names), but will acquire the VG lock on each VG name -argument. - -.I LV lock - -An LV lock is acquired before the LV is activated, and is released after -the LV is deactivated. If the LV lock cannot be acquired, the LV is not -activated. LV locks are persistent and remain in place after the -activation command is done. GL and VG locks are transient, and are held -only while an LVM command is running. - -.I lock retries - -If a request for a GL or VG lock fails due to a lock conflict with another -host, lvmlockd automatically retries for a short time before returning a -failure to the LVM command. If those retries are insufficient, the LVM -command will retry the entire lock request a number of times specified by -global/lvmlockd_lock_retries before failing. If a request for an LV lock -fails due to a lock conflict, the command fails immediately. - - -.SS managing the global lock in sanlock VGs - -The global lock exists in one of the sanlock VGs. The first sanlock VG -created will contain the global lock. Subsequent sanlock VGs will each -contain disabled global locks that can be enabled later if necessary. - -The VG containing the global lock must be visible to all hosts using -sanlock VGs. This can be a reason to create a small sanlock VG, visible -to all hosts, and dedicated to just holding the global lock. While not -required, this strategy can help to avoid difficulty in the future if VGs -are moved or removed. - -The vgcreate command typically acquires the global lock, but in the case -of the first sanlock VG, there will be no global lock to acquire until the -first vgcreate is complete. So, creating the first sanlock VG is a -special case that skips the global lock. - -vgcreate for a sanlock VG determines it is the first one to exist if no -other sanlock VGs are visible. It is possible that other sanlock VGs do -exist but are not visible on the host running vgcreate. In this case, -vgcreate would create a new sanlock VG with the global lock enabled. When -the other VG containing a global lock appears, lvmlockd will see more than -one VG with a global lock enabled, and LVM commands will report that there -are duplicate global locks. - -If the situation arises where more than one sanlock VG contains a global -lock, the global lock should be manually disabled in all but one of them -with the command: - -lvmlockctl \-\-gl\-disable - -(The one VG with the global lock enabled must be visible to all hosts.) - -An opposite problem can occur if the VG holding the global lock is -removed. In this case, no global lock will exist following the vgremove, -and subsequent LVM commands will fail to acquire it. In this case, the -global lock needs to be manually enabled in one of the remaining sanlock -VGs with the command: - -lvmlockctl \-\-gl\-enable - -A small sanlock VG dedicated to holding the global lock can avoid the case -where the GL lock must be manually enabled after a vgremove. - - -.SS internal lvmlock LV - -A sanlock VG contains a hidden LV called "lvmlock" that holds the sanlock -locks. vgreduce cannot yet remove the PV holding the lvmlock LV. To -remove this PV, change the VG lock type to "none", run vgreduce, then -change the VG lock type back to "sanlock". Similarly, pvmove cannot be -used on a PV used by the lvmlock LV. - -To place the lvmlock LV on a specific device, create the VG with only that -device, then use vgextend to add other devices. - - -.SS LV activation - -In a shared VG, activation changes involve locking through lvmlockd, and -the following values are possible with lvchange/vgchange -a: - -.IP \fBy\fP|\fBey\fP -The command activates the LV in exclusive mode, allowing a single host -to activate the LV. Before activating the LV, the command uses lvmlockd -to acquire an exclusive lock on the LV. If the lock cannot be acquired, -the LV is not activated and an error is reported. This would happen if -the LV is active on another host. - -.IP \fBsy\fP -The command activates the LV in shared mode, allowing multiple hosts to -activate the LV concurrently. Before activating the LV, the -command uses lvmlockd to acquire a shared lock on the LV. If the lock -cannot be acquired, the LV is not activated and an error is reported. -This would happen if the LV is active exclusively on another host. If the -LV type prohibits shared access, such as a snapshot, the command will -report an error and fail. -The shared mode is intended for a multi\-host/cluster application or -file system. -LV types that cannot be used concurrently -from multiple hosts include thin, cache, raid, mirror, and snapshot. -lvextend on LV with shared locks is not yet allowed. The LV must be -deactivated, or activated exclusively to run lvextend. - -.IP \fBn\fP -The command deactivates the LV. After deactivating the LV, the command -uses lvmlockd to release the current lock on the LV. - - -.SS recover from lost PV holding sanlock locks - -The general approach is to change the VG lock type to "none", and then -change the lock type back to "sanlock". This recreates the internal -lvmlock LV and the necessary locks on it. Additional steps may be -required to deal with the missing PV. - - -.SS locking system failures - -.B lvmlockd failure - -If lvmlockd fails or is killed while holding locks, the locks are orphaned -in the lock manager. lvmlockd can be restarted with an option to adopt -locks in the lock manager that had been held by the previous instance. - -.B dlm/corosync failure - -If dlm or corosync fail, the clustering system will fence the host using a -method configured within the dlm/corosync clustering environment. - -LVM commands on other hosts will be blocked from acquiring any locks until -the dlm/corosync recovery process is complete. - -.B sanlock lease storage failure - -If the PV under a sanlock VG's lvmlock LV is disconnected, unresponsive or -too slow, sanlock cannot renew the lease for the VG's locks. After some -time, the lease will expire, and locks that the host owns in the VG can be -acquired by other hosts. The VG must be forcibly deactivated on the host -with the expiring lease before other hosts can acquire its locks. - -When the sanlock daemon detects that the lease storage is lost, it runs -the command lvmlockctl \-\-kill . This command emits a syslog -message stating that lease storage is lost for the VG and LVs must be -immediately deactivated. - -If no LVs are active in the VG, then the lockspace with an expiring lease -will be removed, and errors will be reported when trying to use the VG. -Use the lvmlockctl \-\-drop command to clear the stale lockspace from -lvmlockd. - -If the VG has active LVs when the lock storage is lost, the LVs must be -quickly deactivated before the lockspace lease expires. After all LVs are -deactivated, run lvmlockctl \-\-drop to clear the expiring -lockspace from lvmlockd. If all LVs in the VG are not deactivated within -about 40 seconds, sanlock will reset the host using the local watchdog. -The machine reset is effectively a severe form of "deactivating" LVs -before they can be activated on other hosts. The reset is considered a -better alternative than having LVs used by multiple hosts at once, which -could easily damage or destroy their content. - -In the future, the lvmlockctl kill command may automatically attempt to -forcibly deactivate LVs before the sanlock lease expires. Until then, the -user must notice the syslog message and manually deactivate the VG before -sanlock resets the machine. - -.B sanlock daemon failure - -If the sanlock daemon fails or exits while a lockspace is started, the -local watchdog will reset the host. This is necessary to protect any -application resources that depend on sanlock leases which will be lost -without sanlock running. - - -.SS changing dlm cluster name - -When a dlm VG is created, the cluster name is saved in the VG metadata. -To use the VG, a host must be in the named dlm cluster. If the dlm -cluster name changes, or the VG is moved to a new cluster, the dlm cluster -name saved in the VG must also be changed. - -To see the dlm cluster name saved in the VG, use the command: -.br -vgs -o+locktype,lockargs - -To change the dlm cluster name in the VG when the VG is still used by the -original cluster: - -.IP \[bu] 2 -Stop the VG on all hosts: -.br -vgchange --lock-stop - -.IP \[bu] 2 -Change the VG lock type to none: -.br -vgchange \-\-lock\-type none - -.IP \[bu] 2 -Change the dlm cluster name on the host or move the VG to the new cluster. -The new dlm cluster must now be active on the host. Verify the new name -by: -.br -cat /sys/kernel/config/dlm/cluster/cluster_name - -.IP \[bu] 2 -Change the VG lock type back to dlm which sets the new cluster name: -.br -vgchange \-\-lock\-type dlm - -.IP \[bu] 2 -Start the VG on hosts to use it: -.br -vgchange --lock-start - -.P - -To change the dlm cluster name in the VG when the dlm cluster name has -already changed, or the VG has already moved to a different cluster: - -.IP \[bu] 2 -Ensure the VG is not being used by any hosts. - -.IP \[bu] 2 -The new dlm cluster must be active on the host making the change. -The current dlm cluster name can be seen by: -.br -cat /sys/kernel/config/dlm/cluster/cluster_name - -.IP \[bu] 2 -Change the VG lock type to none: -.br -vgchange \-\-lock\-type none \-\-force - -.IP \[bu] 2 -Change the VG lock type back to dlm which sets the new cluster name: -.br -vgchange \-\-lock\-type dlm - -.IP \[bu] 2 -Start the VG on hosts to use it: -.br -vgchange --lock-start - - -.SS changing a local VG to a lockd VG - -All LVs must be inactive to change the lock type. - -lvmlockd must be configured and running as described in USAGE. - -Change a local VG to a lockd VG with the command: -.br -vgchange \-\-lock\-type sanlock|dlm - -Start the VG on hosts to use it: -.br -vgchange \-\-lock\-start - - -.SS changing a lockd VG to a local VG - -Stop the lockd VG on all hosts, then run: -.br -vgchange \-\-lock\-type none - -To change a VG from one lockd type to another (i.e. between sanlock and -dlm), first change it to a local VG, then to the new type. - - -.SS changing a clvm VG to a lockd VG - -All LVs must be inactive to change the lock type. - -First change the clvm VG to a local VG. Within a running clvm cluster, -change a clvm VG to a local VG with the command: - -vgchange \-cn - -If the clvm cluster is no longer running on any nodes, then extra options -can be used to forcibly make the VG local. Caution: this is only safe if -all nodes have stopped using the VG: - -vgchange \-\-config 'global/locking_type=0 global/use_lvmlockd=0' -.RS -\-cn -.RE - -After the VG is local, follow the steps described in "changing a local VG -to a lockd VG". - - -.SS limitations of lockd VGs - -Things that do not yet work in lockd VGs: -.br -\[bu] -creating a new thin pool and a new thin LV in a single command -.br -\[bu] -using lvcreate to create cache pools or cache LVs (use lvconvert) -.br -\[bu] -using external origins for thin LVs -.br -\[bu] -splitting mirrors and snapshots from LVs -.br -\[bu] -vgsplit -.br -\[bu] -vgmerge -.br -\[bu] -resizing an LV that is active in the shared mode on multiple hosts - - -.SS lvmlockd changes from clvmd - -(See above for converting an existing clvm VG to a lockd VG.) - -While lvmlockd and clvmd are entirely different systems, LVM command usage -remains similar. Differences are more notable when using lvmlockd's -sanlock option. - -Visible usage differences between lockd VGs with lvmlockd and clvm VGs -with clvmd: - -.IP \[bu] 2 -lvm.conf must be configured to use either lvmlockd (use_lvmlockd=1) or -clvmd (locking_type=3), but not both. - -.IP \[bu] 2 -vgcreate \-\-shared creates a lockd VG, and vgcreate \-\-clustered y -creates a clvm VG. - -.IP \[bu] 2 -lvmlockd adds the option of using sanlock for locking, avoiding the -need for network clustering. - -.IP \[bu] 2 -lvmlockd defaults to the exclusive activation mode whenever the activation -mode is unspecified, i.e. \-ay means \-aey, not \-asy. - -.IP \[bu] 2 -lvmlockd commands always apply to the local host, and never have an effect -on a remote host. (The activation option 'l' is not used.) - -.IP \[bu] 2 -lvmlockd works with thin and cache pools and LVs. - -.IP \[bu] 2 -lvmlockd works with lvmetad. - -.IP \[bu] 2 -lvmlockd saves the cluster name for a lockd VG using dlm. Only hosts in -the matching cluster can use the VG. - -.IP \[bu] 2 -lvmlockd requires starting/stopping lockd VGs with vgchange \-\-lock-start -and \-\-lock-stop. - -.IP \[bu] 2 -vgremove of a sanlock VG may fail indicating that all hosts have not -stopped the VG lockspace. Stop the VG on all hosts using vgchange -\-\-lock-stop. - -.IP \[bu] 2 -vgreduce or pvmove of a PV in a sanlock VG will fail if it holds the -internal "lvmlock" LV that holds the sanlock locks. - -.IP \[bu] 2 -lvmlockd uses lock retries instead of lock queueing, so high lock -contention may require increasing global/lvmlockd_lock_retries to -avoid transient lock failures. - -.IP \[bu] 2 -lvmlockd includes VG reporting options lock_type and lock_args, and LV -reporting option lock_args to view the corresponding metadata fields. - -.IP \[bu] 2 -In the 'vgs' command's sixth VG attr field, "s" for "shared" is displayed -for lockd VGs. - -.IP \[bu] 2 -If lvmlockd fails or is killed while in use, locks it held remain but are -orphaned in the lock manager. lvmlockd can be restarted with an option to -adopt the orphan locks from the previous instance of lvmlockd. - -.P diff --git a/man/lvmlockd.8_main b/man/lvmlockd.8_main new file mode 100644 index 0000000..6e9b703 --- /dev/null +++ b/man/lvmlockd.8_main @@ -0,0 +1,889 @@ +.TH "LVMLOCKD" "8" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" + +.SH NAME +lvmlockd \(em LVM locking daemon + +.SH DESCRIPTION +LVM commands use lvmlockd to coordinate access to shared storage. +.br +When LVM is used on devices shared by multiple hosts, locks will: + +\[bu] +coordinate reading and writing of LVM metadata +.br +\[bu] +validate caching of LVM metadata +.br +\[bu] +prevent concurrent activation of logical volumes +.br + +lvmlockd uses an external lock manager to perform basic locking. +.br +Lock manager (lock type) options are: + +\[bu] +sanlock: places locks on disk within LVM storage. +.br +\[bu] +dlm: uses network communication and a cluster manager. +.br + +.SH OPTIONS + +lvmlockd [options] + +For default settings, see lvmlockd \-h. + +.B \-\-help | \-h + Show this help information. + +.B \-\-version | \-V + Show version of lvmlockd. + +.B \-\-test | \-T + Test mode, do not call lock manager. + +.B \-\-foreground | \-f + Don't fork. + +.B \-\-daemon\-debug | \-D + Don't fork and print debugging to stdout. + +.B \-\-pid\-file | \-p +.I path + Set path to the pid file. + +.B \-\-socket\-path | \-s +.I path + Set path to the socket to listen on. + +.B \-\-syslog\-priority | \-S err|warning|debug + Write log messages from this level up to syslog. + +.B \-\-gl\-type | \-g sanlock|dlm + Set global lock type to be sanlock or dlm. + +.B \-\-host\-id | \-i +.I num + Set the local sanlock host id. + +.B \-\-host\-id\-file | \-F +.I path + A file containing the local sanlock host_id. + +.B \-\-sanlock\-timeout | \-o +.I seconds + Override the default sanlock I/O timeout. + +.B \-\-adopt | \-A 0|1 + Adopt locks from a previous instance of lvmlockd. + + +.SH USAGE + +.SS Initial set up + +Using LVM with lvmlockd for the first time includes some one\-time set up +steps: + +.SS 1. choose a lock manager + +.I dlm +.br +If dlm (or corosync) are already being used by other cluster +software, then select dlm. dlm uses corosync which requires additional +configuration beyond the scope of this document. See corosync and dlm +documentation for instructions on configuration, setup and usage. + +.I sanlock +.br +Choose sanlock if dlm/corosync are not otherwise required. +sanlock does not depend on any clustering software or configuration. + +.SS 2. configure hosts to use lvmlockd + +On all hosts running lvmlockd, configure lvm.conf: +.nf +locking_type = 1 +use_lvmlockd = 1 +.fi + +.I sanlock +.br +Assign each host a unique host_id in the range 1\-2000 by setting +.br +/etc/lvm/lvmlocal.conf local/host_id + +.SS 3. start lvmlockd + +Use a service/init file if available, or just run "lvmlockd". + +.SS 4. start lock manager + +.I sanlock +.br +systemctl start wdmd sanlock + +.I dlm +.br +Follow external clustering documentation when applicable, otherwise: +.br +systemctl start corosync dlm + +.SS 5. create VG on shared devices + +vgcreate \-\-shared + +The shared option sets the VG lock type to sanlock or dlm depending on +which lock manager is running. LVM commands will perform locking for the +VG using lvmlockd. lvmlockd will use the chosen lock manager. + +.SS 6. start VG on all hosts + +vgchange \-\-lock\-start + +lvmlockd requires shared VGs to be started before they are used. This is +a lock manager operation to start (join) the VG lockspace, and it may take +some time. Until the start completes, locks for the VG are not available. +LVM commands are allowed to read the VG while start is in progress. (An +init/unit file can also be used to start VGs.) + +.SS 7. create and activate LVs + +Standard lvcreate and lvchange commands are used to create and activate +LVs in a shared VG. + +An LV activated exclusively on one host cannot be activated on another. +When multiple hosts need to use the same LV concurrently, the LV can be +activated with a shared lock (see lvchange options \-aey vs \-asy.) +(Shared locks are disallowed for certain LV types that cannot be used from +multiple hosts.) + + +.SS Normal start up and shut down + +After initial set up, start up and shut down include the following general +steps. They can be performed manually or using the system service +manager. + +\[bu] +start lvmetad +.br +\[bu] +start lvmlockd +.br +\[bu] +start lock manager +.br +\[bu] +vgchange \-\-lock\-start +.br +\[bu] +activate LVs in shared VGs +.br + +The shut down sequence is the reverse: + +\[bu] +deactivate LVs in shared VGs +.br +\[bu] +vgchange \-\-lock\-stop +.br +\[bu] +stop lock manager +.br +\[bu] +stop lvmlockd +.br +\[bu] +stop lvmetad +.br + +.P + +.SH TOPICS + +.SS VG access control + +The following terms are used to describe different forms of VG access +control. + +.I "lockd VG" + +A "lockd VG" is a shared VG that has a "lock type" of dlm or sanlock. +Using it requires lvmlockd. These VGs exist on shared storage that is +visible to multiple hosts. LVM commands use lvmlockd to perform locking +for these VGs when they are used. + +If the lock manager for the lock type is not available (e.g. not started +or failed), lvmlockd is unable to acquire locks for LVM commands. LVM +commands that only read the VG will generally be allowed to continue +without locks in this case (with a warning). Commands to modify or +activate the VG will fail without the necessary locks. + +.I "local VG" + +A "local VG" is meant to be used by a single host. It has no lock type or +lock type "none". LVM commands and lvmlockd do not perform locking for +these VGs. A local VG typically exists on local (non\-shared) devices and +cannot be used concurrently from different hosts. + +If a local VG does exist on shared devices, it should be owned by a single +host by having its system ID set, see +.BR lvmsystemid (7). +Only the host with a matching system ID can use the local VG. A VG +with no lock type and no system ID should be excluded from all but one +host using lvm.conf filters. Without any of these protections, a local VG +on shared devices can be easily damaged or destroyed. + +.I "clvm VG" + +A "clvm VG" is a VG on shared storage (like a lockd VG) that requires +clvmd for clustering. See below for converting a clvm VG to a lockd VG. + + +.SS lockd VGs from hosts not using lvmlockd + +Only hosts that use lockd VGs should be configured to run lvmlockd. +However, shared devices used by lockd VGs may be visible from hosts not +using lvmlockd. From a host not using lvmlockd, visible lockd VGs are +ignored in the same way as foreign VGs (see +.BR lvmsystemid (7).) + +The \-\-shared option for reporting and display commands causes lockd VGs +to be displayed on a host not using lvmlockd, like the \-\-foreign option +does for foreign VGs. + + +.SS vgcreate comparison + +The type of VG access control is specified in the vgcreate command. +See +.BR vgcreate (8) +for all vgcreate options. + +.B vgcreate + +.IP \[bu] 2 +Creates a local VG with the local system ID when neither lvmlockd nor clvm are configured. +.IP \[bu] 2 +Creates a local VG with the local system ID when lvmlockd is configured. +.IP \[bu] 2 +Creates a clvm VG when clvm is configured. + +.P + +.B vgcreate \-\-shared +.IP \[bu] 2 +Requires lvmlockd to be configured and running. +.IP \[bu] 2 +Creates a lockd VG with lock type sanlock|dlm depending on which lock +manager is running. +.IP \[bu] 2 +LVM commands request locks from lvmlockd to use the VG. +.IP \[bu] 2 +lvmlockd obtains locks from the selected lock manager. + +.P + +.B vgcreate \-c|\-\-clustered y +.IP \[bu] 2 +Requires clvm to be configured and running. +.IP \[bu] 2 +Creates a clvm VG with the "clustered" flag. +.IP \[bu] 2 +LVM commands request locks from clvmd to use the VG. + +.P + +.SS creating the first sanlock VG + +Creating the first sanlock VG is not protected by locking and requires +special attention. This is because sanlock locks exist within the VG, so +they are not available until the VG exists. The first sanlock VG will +contain the "global lock". + +.IP \[bu] 2 +The first vgcreate command needs to be given the path to a device that has +not yet been initialized with pvcreate. The pvcreate initialization will +be done by vgcreate. This is because the pvcreate command requires the +global lock, which will not be available until after the first sanlock VG +is created. + +.IP \[bu] 2 +While running vgcreate for the first sanlock VG, ensure that the device +being used is not used by another LVM command. Allocation of shared +devices is usually protected by the global lock, but this cannot be done +for the first sanlock VG which will hold the global lock. + +.IP \[bu] 2 +While running vgcreate for the first sanlock VG, ensure that the VG name +being used is not used by another LVM command. Uniqueness of VG names is +usually ensured by the global lock. + +.IP \[bu] 2 +Because the first sanlock VG will contain the global lock, this VG needs +to be accessible to all hosts that will use sanlock shared VGs. All hosts +will need to use the global lock from the first sanlock VG. + +See below for more information about managing the sanlock global lock. + + +.SS using lockd VGs + +There are some special considerations when using lockd VGs. + +When use_lvmlockd is first enabled in lvm.conf, and before the first lockd +VG is created, no global lock will exist. In this initial state, LVM +commands try and fail to acquire the global lock, producing a warning, and +some commands are disallowed. Once the first lockd VG is created, the +global lock will be available, and LVM will be fully operational. + +When a new lockd VG is created, its lockspace is automatically started on +the host that creates it. Other hosts need to run 'vgchange +\-\-lock\-start' to start the new VG before they can use it. + +From the 'vgs' command, lockd VGs are indicated by "s" (for shared) in the +sixth attr field. The specific lock type and lock args for a lockd VG can +be displayed with 'vgs \-o+locktype,lockargs'. + +lockd VGs need to be "started" and "stopped", unlike other types of VGs. +See the following section for a full description of starting and stopping. + +vgremove of a lockd VG will fail if other hosts have the VG started. +Run vgchange \-\-lock-stop on all other hosts before vgremove. +(It may take several seconds before vgremove recognizes that all hosts +have stopped a sanlock VG.) + +.SS starting and stopping VGs + +Starting a lockd VG (vgchange \-\-lock\-start) causes the lock manager to +start (join) the lockspace for the VG on the host where it is run. This +makes locks for the VG available to LVM commands on the host. Before a VG +is started, only LVM commands that read/display the VG are allowed to +continue without locks (and with a warning). + +Stopping a lockd VG (vgchange \-\-lock\-stop) causes the lock manager to +stop (leave) the lockspace for the VG on the host where it is run. This +makes locks for the VG inaccessible to the host. A VG cannot be stopped +while it has active LVs. + +When using the lock type sanlock, starting a VG can take a long time +(potentially minutes if the host was previously shut down without cleanly +stopping the VG.) + +A lockd VG can be started after all the following are true: +.br +\[bu] +lvmlockd is running +.br +\[bu] +the lock manager is running +.br +\[bu] +the VG is visible to the system +.br + +A lockd VG can be stopped if all LVs are deactivated. + +All lockd VGs can be started/stopped using: +.br +vgchange \-\-lock-start +.br +vgchange \-\-lock-stop + + +Individual VGs can be started/stopped using: +.br +vgchange \-\-lock\-start ... +.br +vgchange \-\-lock\-stop ... + +To make vgchange not wait for start to complete: +.br +vgchange \-\-lock\-start \-\-lock\-opt nowait ... + +lvmlockd can be asked directly to stop all lockspaces: +.br +lvmlockctl \-\-stop\-lockspaces + +To start only selected lockd VGs, use the lvm.conf +activation/lock_start_list. When defined, only VG names in this list are +started by vgchange. If the list is not defined (the default), all +visible lockd VGs are started. To start only "vg1", use the following +lvm.conf configuration: + +.nf +activation { + lock_start_list = [ "vg1" ] + ... +} +.fi + + +.SS automatic starting and automatic activation + +Scripts or programs on a host that automatically start VGs will use the +"auto" option to indicate that the command is being run automatically by +the system: + +vgchange \-\-lock\-start \-\-lock\-opt auto [ ...] + +Without any additional configuration, including the "auto" option has no +effect; all VGs are started unless restricted by lock_start_list. + +However, when the lvm.conf activation/auto_lock_start_list is defined, the +auto start command performs an additional filtering phase to all VGs being +started, testing each VG name against the auto_lock_start_list. The +auto_lock_start_list defines lockd VGs that will be started by the auto +start command. Visible lockd VGs not included in the list are ignored by +the auto start command. If the list is undefined, all VG names pass this +filter. (The lock_start_list is also still used to filter all VGs.) + +The auto_lock_start_list allows a user to select certain lockd VGs that +should be automatically started by the system (or indirectly, those that +should not). + +To use auto activation of lockd LVs (see auto_activation_volume_list), +auto starting of the corresponding lockd VGs is necessary. + + +.SS internal command locking + +To optimize the use of LVM with lvmlockd, be aware of the three kinds of +locks and when they are used: + +.I GL lock + +The global lock (GL lock) is associated with global information, which is +information not isolated to a single VG. This includes: + +\[bu] +The global VG namespace. +.br +\[bu] +The set of orphan PVs and unused devices. +.br +\[bu] +The properties of orphan PVs, e.g. PV size. +.br + +The global lock is used in shared mode by commands that read this +information, or in exclusive mode by commands that change it. + +The command 'vgs' acquires the global lock in shared mode because it +reports the list of all VG names. + +The vgcreate command acquires the global lock in exclusive mode because it +creates a new VG name, and it takes a PV from the list of unused PVs. + +When an LVM command is given a tag argument, or uses select, it must read +all VGs to match the tag or selection, which causes the global lock to be +acquired. + +.I VG lock + +A VG lock is associated with each VG. The VG lock is acquired in shared +mode to read the VG and in exclusive mode to change the VG (modify the VG +metadata or activate LVs). This lock serializes access to a VG with all +other LVM commands accessing the VG from all hosts. + +The command 'vgs' will not only acquire the GL lock to read the list of +all VG names, but will acquire the VG lock for each VG prior to reading +it. + +The command 'vgs ' does not acquire the GL lock (it does not need +the list of all VG names), but will acquire the VG lock on each VG name +argument. + +.I LV lock + +An LV lock is acquired before the LV is activated, and is released after +the LV is deactivated. If the LV lock cannot be acquired, the LV is not +activated. LV locks are persistent and remain in place after the +activation command is done. GL and VG locks are transient, and are held +only while an LVM command is running. + +.I lock retries + +If a request for a GL or VG lock fails due to a lock conflict with another +host, lvmlockd automatically retries for a short time before returning a +failure to the LVM command. If those retries are insufficient, the LVM +command will retry the entire lock request a number of times specified by +global/lvmlockd_lock_retries before failing. If a request for an LV lock +fails due to a lock conflict, the command fails immediately. + + +.SS managing the global lock in sanlock VGs + +The global lock exists in one of the sanlock VGs. The first sanlock VG +created will contain the global lock. Subsequent sanlock VGs will each +contain disabled global locks that can be enabled later if necessary. + +The VG containing the global lock must be visible to all hosts using +sanlock VGs. This can be a reason to create a small sanlock VG, visible +to all hosts, and dedicated to just holding the global lock. While not +required, this strategy can help to avoid difficulty in the future if VGs +are moved or removed. + +The vgcreate command typically acquires the global lock, but in the case +of the first sanlock VG, there will be no global lock to acquire until the +first vgcreate is complete. So, creating the first sanlock VG is a +special case that skips the global lock. + +vgcreate for a sanlock VG determines it is the first one to exist if no +other sanlock VGs are visible. It is possible that other sanlock VGs do +exist but are not visible on the host running vgcreate. In this case, +vgcreate would create a new sanlock VG with the global lock enabled. When +the other VG containing a global lock appears, lvmlockd will see more than +one VG with a global lock enabled, and LVM commands will report that there +are duplicate global locks. + +If the situation arises where more than one sanlock VG contains a global +lock, the global lock should be manually disabled in all but one of them +with the command: + +lvmlockctl \-\-gl\-disable + +(The one VG with the global lock enabled must be visible to all hosts.) + +An opposite problem can occur if the VG holding the global lock is +removed. In this case, no global lock will exist following the vgremove, +and subsequent LVM commands will fail to acquire it. In this case, the +global lock needs to be manually enabled in one of the remaining sanlock +VGs with the command: + +lvmlockctl \-\-gl\-enable + +A small sanlock VG dedicated to holding the global lock can avoid the case +where the GL lock must be manually enabled after a vgremove. + + +.SS internal lvmlock LV + +A sanlock VG contains a hidden LV called "lvmlock" that holds the sanlock +locks. vgreduce cannot yet remove the PV holding the lvmlock LV. To +remove this PV, change the VG lock type to "none", run vgreduce, then +change the VG lock type back to "sanlock". Similarly, pvmove cannot be +used on a PV used by the lvmlock LV. + +To place the lvmlock LV on a specific device, create the VG with only that +device, then use vgextend to add other devices. + + +.SS LV activation + +In a shared VG, activation changes involve locking through lvmlockd, and +the following values are possible with lvchange/vgchange -a: + +.IP \fBy\fP|\fBey\fP +The command activates the LV in exclusive mode, allowing a single host +to activate the LV. Before activating the LV, the command uses lvmlockd +to acquire an exclusive lock on the LV. If the lock cannot be acquired, +the LV is not activated and an error is reported. This would happen if +the LV is active on another host. + +.IP \fBsy\fP +The command activates the LV in shared mode, allowing multiple hosts to +activate the LV concurrently. Before activating the LV, the +command uses lvmlockd to acquire a shared lock on the LV. If the lock +cannot be acquired, the LV is not activated and an error is reported. +This would happen if the LV is active exclusively on another host. If the +LV type prohibits shared access, such as a snapshot, the command will +report an error and fail. +The shared mode is intended for a multi\-host/cluster application or +file system. +LV types that cannot be used concurrently +from multiple hosts include thin, cache, raid, mirror, and snapshot. +lvextend on LV with shared locks is not yet allowed. The LV must be +deactivated, or activated exclusively to run lvextend. + +.IP \fBn\fP +The command deactivates the LV. After deactivating the LV, the command +uses lvmlockd to release the current lock on the LV. + + +.SS recover from lost PV holding sanlock locks + +The general approach is to change the VG lock type to "none", and then +change the lock type back to "sanlock". This recreates the internal +lvmlock LV and the necessary locks on it. Additional steps may be +required to deal with the missing PV. + + +.SS locking system failures + +.B lvmlockd failure + +If lvmlockd fails or is killed while holding locks, the locks are orphaned +in the lock manager. lvmlockd can be restarted with an option to adopt +locks in the lock manager that had been held by the previous instance. + +.B dlm/corosync failure + +If dlm or corosync fail, the clustering system will fence the host using a +method configured within the dlm/corosync clustering environment. + +LVM commands on other hosts will be blocked from acquiring any locks until +the dlm/corosync recovery process is complete. + +.B sanlock lease storage failure + +If the PV under a sanlock VG's lvmlock LV is disconnected, unresponsive or +too slow, sanlock cannot renew the lease for the VG's locks. After some +time, the lease will expire, and locks that the host owns in the VG can be +acquired by other hosts. The VG must be forcibly deactivated on the host +with the expiring lease before other hosts can acquire its locks. + +When the sanlock daemon detects that the lease storage is lost, it runs +the command lvmlockctl \-\-kill . This command emits a syslog +message stating that lease storage is lost for the VG and LVs must be +immediately deactivated. + +If no LVs are active in the VG, then the lockspace with an expiring lease +will be removed, and errors will be reported when trying to use the VG. +Use the lvmlockctl \-\-drop command to clear the stale lockspace from +lvmlockd. + +If the VG has active LVs when the lock storage is lost, the LVs must be +quickly deactivated before the lockspace lease expires. After all LVs are +deactivated, run lvmlockctl \-\-drop to clear the expiring +lockspace from lvmlockd. If all LVs in the VG are not deactivated within +about 40 seconds, sanlock will reset the host using the local watchdog. +The machine reset is effectively a severe form of "deactivating" LVs +before they can be activated on other hosts. The reset is considered a +better alternative than having LVs used by multiple hosts at once, which +could easily damage or destroy their content. + +In the future, the lvmlockctl kill command may automatically attempt to +forcibly deactivate LVs before the sanlock lease expires. Until then, the +user must notice the syslog message and manually deactivate the VG before +sanlock resets the machine. + +.B sanlock daemon failure + +If the sanlock daemon fails or exits while a lockspace is started, the +local watchdog will reset the host. This is necessary to protect any +application resources that depend on sanlock leases which will be lost +without sanlock running. + + +.SS changing dlm cluster name + +When a dlm VG is created, the cluster name is saved in the VG metadata. +To use the VG, a host must be in the named dlm cluster. If the dlm +cluster name changes, or the VG is moved to a new cluster, the dlm cluster +name saved in the VG must also be changed. + +To see the dlm cluster name saved in the VG, use the command: +.br +vgs -o+locktype,lockargs + +To change the dlm cluster name in the VG when the VG is still used by the +original cluster: + +.IP \[bu] 2 +Stop the VG on all hosts: +.br +vgchange --lock-stop + +.IP \[bu] 2 +Change the VG lock type to none: +.br +vgchange \-\-lock\-type none + +.IP \[bu] 2 +Change the dlm cluster name on the host or move the VG to the new cluster. +The new dlm cluster must now be active on the host. Verify the new name +by: +.br +cat /sys/kernel/config/dlm/cluster/cluster_name + +.IP \[bu] 2 +Change the VG lock type back to dlm which sets the new cluster name: +.br +vgchange \-\-lock\-type dlm + +.IP \[bu] 2 +Start the VG on hosts to use it: +.br +vgchange --lock-start + +.P + +To change the dlm cluster name in the VG when the dlm cluster name has +already changed, or the VG has already moved to a different cluster: + +.IP \[bu] 2 +Ensure the VG is not being used by any hosts. + +.IP \[bu] 2 +The new dlm cluster must be active on the host making the change. +The current dlm cluster name can be seen by: +.br +cat /sys/kernel/config/dlm/cluster/cluster_name + +.IP \[bu] 2 +Change the VG lock type to none: +.br +vgchange \-\-lock\-type none \-\-force + +.IP \[bu] 2 +Change the VG lock type back to dlm which sets the new cluster name: +.br +vgchange \-\-lock\-type dlm + +.IP \[bu] 2 +Start the VG on hosts to use it: +.br +vgchange --lock-start + + +.SS changing a local VG to a lockd VG + +All LVs must be inactive to change the lock type. + +lvmlockd must be configured and running as described in USAGE. + +Change a local VG to a lockd VG with the command: +.br +vgchange \-\-lock\-type sanlock|dlm + +Start the VG on hosts to use it: +.br +vgchange \-\-lock\-start + + +.SS changing a lockd VG to a local VG + +Stop the lockd VG on all hosts, then run: +.br +vgchange \-\-lock\-type none + +To change a VG from one lockd type to another (i.e. between sanlock and +dlm), first change it to a local VG, then to the new type. + + +.SS changing a clvm VG to a lockd VG + +All LVs must be inactive to change the lock type. + +First change the clvm VG to a local VG. Within a running clvm cluster, +change a clvm VG to a local VG with the command: + +vgchange \-cn + +If the clvm cluster is no longer running on any nodes, then extra options +can be used to forcibly make the VG local. Caution: this is only safe if +all nodes have stopped using the VG: + +vgchange \-\-config 'global/locking_type=0 global/use_lvmlockd=0' +.RS +\-cn +.RE + +After the VG is local, follow the steps described in "changing a local VG +to a lockd VG". + + +.SS limitations of lockd VGs + +Things that do not yet work in lockd VGs: +.br +\[bu] +creating a new thin pool and a new thin LV in a single command +.br +\[bu] +using lvcreate to create cache pools or cache LVs (use lvconvert) +.br +\[bu] +using external origins for thin LVs +.br +\[bu] +splitting mirrors and snapshots from LVs +.br +\[bu] +vgsplit +.br +\[bu] +vgmerge +.br +\[bu] +resizing an LV that is active in the shared mode on multiple hosts + + +.SS lvmlockd changes from clvmd + +(See above for converting an existing clvm VG to a lockd VG.) + +While lvmlockd and clvmd are entirely different systems, LVM command usage +remains similar. Differences are more notable when using lvmlockd's +sanlock option. + +Visible usage differences between lockd VGs with lvmlockd and clvm VGs +with clvmd: + +.IP \[bu] 2 +lvm.conf must be configured to use either lvmlockd (use_lvmlockd=1) or +clvmd (locking_type=3), but not both. + +.IP \[bu] 2 +vgcreate \-\-shared creates a lockd VG, and vgcreate \-\-clustered y +creates a clvm VG. + +.IP \[bu] 2 +lvmlockd adds the option of using sanlock for locking, avoiding the +need for network clustering. + +.IP \[bu] 2 +lvmlockd defaults to the exclusive activation mode whenever the activation +mode is unspecified, i.e. \-ay means \-aey, not \-asy. + +.IP \[bu] 2 +lvmlockd commands always apply to the local host, and never have an effect +on a remote host. (The activation option 'l' is not used.) + +.IP \[bu] 2 +lvmlockd works with thin and cache pools and LVs. + +.IP \[bu] 2 +lvmlockd works with lvmetad. + +.IP \[bu] 2 +lvmlockd saves the cluster name for a lockd VG using dlm. Only hosts in +the matching cluster can use the VG. + +.IP \[bu] 2 +lvmlockd requires starting/stopping lockd VGs with vgchange \-\-lock-start +and \-\-lock-stop. + +.IP \[bu] 2 +vgremove of a sanlock VG may fail indicating that all hosts have not +stopped the VG lockspace. Stop the VG on all hosts using vgchange +\-\-lock-stop. + +.IP \[bu] 2 +vgreduce or pvmove of a PV in a sanlock VG will fail if it holds the +internal "lvmlock" LV that holds the sanlock locks. + +.IP \[bu] 2 +lvmlockd uses lock retries instead of lock queueing, so high lock +contention may require increasing global/lvmlockd_lock_retries to +avoid transient lock failures. + +.IP \[bu] 2 +lvmlockd includes VG reporting options lock_type and lock_args, and LV +reporting option lock_args to view the corresponding metadata fields. + +.IP \[bu] 2 +In the 'vgs' command's sixth VG attr field, "s" for "shared" is displayed +for lockd VGs. + +.IP \[bu] 2 +If lvmlockd fails or is killed while in use, locks it held remain but are +orphaned in the lock manager. lvmlockd can be restarted with an option to +adopt the orphan locks from the previous instance of lvmlockd. + +.P diff --git a/man/lvmpolld.8.in b/man/lvmpolld.8.in deleted file mode 100644 index 00ee1ab..0000000 --- a/man/lvmpolld.8.in +++ /dev/null @@ -1,90 +0,0 @@ -.TH LVMPOLLD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- -.SH NAME -lvmpolld \(em LVM poll daemon -.SH SYNOPSIS -.B lvmpolld -.RB [ \-l | \-\-log -.RI { all | wire | debug }] -.RB [ \-p | \-\-pidfile -.IR pidfile_path ] -.RB [ \-s | \-\-socket -.IR socket_path ] -.RB [ \-B | \-\-binary -.IR lvm_binary_path ] -.RB [ \-t | \-\-timeout -.IR timeout_value ] -.RB [ \-f | \-\-foreground ] -.RB [ \-h | \-\-help ] -.RB [ \-V | \-\-version ] - -.B lvmpolld -.RB [ \-\-dump ] -.SH DESCRIPTION -lvmpolld is polling daemon for LVM. The daemon receives requests for polling -of already initialised operations originating in LVM2 command line tool. -The requests for polling originate in the \fBlvconvert\fP, \fBpvmove\fP, -\fBlvchange\fP or \fBvgchange\fP LVM2 commands. - -The purpose of lvmpolld is to reduce the number of spawned background processes -per otherwise unique polling operation. There should be only one. It also -eliminates the possibility of unsolicited termination of background process by -external factors. - -lvmpolld is used by LVM only if it is enabled in \fBlvm.conf\fP(5) by -specifying the \fBglobal/use_lvmpolld\fP setting. If this is not defined in the -LVM configuration explicitly then default setting is used instead (see the -output of \fBlvmconfig \-\-type default global/use_lvmpolld\fP command). -.SH OPTIONS - -To run the daemon in a test environment both the pidfile_path and the -socket_path should be changed from the defaults. -.TP -.BR \-f ", " \-\-foreground -Don't fork, but run in the foreground. -.TP -.BR \-h ", " \-\-help -Show help information. -.TP -.IR \fB\-l\fP ", " \fB\-\-log\fP " {" all | wire | debug } -Select the type of log messages to generate. -Messages are logged by syslog. -Additionally, when \-f is given they are also sent to standard error. -There are two classes of messages: wire and debug. Selecting 'all' supplies both -and is equivalent to a comma-separated list \-l wire,debug. -.TP -.BR \-p ", " \-\-pidfile " " \fIpidfile_path -Path to the pidfile. This overrides both the built-in default -(#DEFAULT_PID_DIR#/lvmpolld.pid) and the environment variable -\fBLVM_LVMPOLLD_PIDFILE\fP. This file is used to prevent more -than one instance of the daemon running simultaneously. -.TP -.BR \-s ", " \-\-socket " " \fIsocket_path -Path to the socket file. This overrides both the built-in default -(#DEFAULT_RUN_DIR#/lvmpolld.socket) and the environment variable -\fBLVM_LVMPOLLD_SOCKET\fP. -.TP -.BR \-t ", " \-\-timeout " " \fItimeout_value -The daemon may shutdown after being idle for the given time (in seconds). When the -option is omitted or the value given is zero the daemon never shutdowns on idle. -.TP -.BR \-B ", " \-\-binary " " \fIlvm_binary_path -Optional path to alternative LVM binary (default: #LVM_PATH#). Use for -testing purposes only. -.TP -.BR \-V ", " \-\-version -Display the version of lvmpolld daemon. -.TP -.B \-\-dump -Contact the running lvmpolld daemon to obtain the complete state and print it -out in a raw format. -.SH ENVIRONMENT VARIABLES -.TP -.B LVM_LVMPOLLD_PIDFILE -Path for the pid file. -.TP -.B LVM_LVMPOLLD_SOCKET -Path for the socket file. - -.SH SEE ALSO -.BR lvm (8), -.BR lvm.conf (5) diff --git a/man/lvmpolld.8_main b/man/lvmpolld.8_main new file mode 100644 index 0000000..00ee1ab --- /dev/null +++ b/man/lvmpolld.8_main @@ -0,0 +1,90 @@ +.TH LVMPOLLD 8 "LVM TOOLS #VERSION#" "Red Hat Inc" \" -*- nroff -*- +.SH NAME +lvmpolld \(em LVM poll daemon +.SH SYNOPSIS +.B lvmpolld +.RB [ \-l | \-\-log +.RI { all | wire | debug }] +.RB [ \-p | \-\-pidfile +.IR pidfile_path ] +.RB [ \-s | \-\-socket +.IR socket_path ] +.RB [ \-B | \-\-binary +.IR lvm_binary_path ] +.RB [ \-t | \-\-timeout +.IR timeout_value ] +.RB [ \-f | \-\-foreground ] +.RB [ \-h | \-\-help ] +.RB [ \-V | \-\-version ] + +.B lvmpolld +.RB [ \-\-dump ] +.SH DESCRIPTION +lvmpolld is polling daemon for LVM. The daemon receives requests for polling +of already initialised operations originating in LVM2 command line tool. +The requests for polling originate in the \fBlvconvert\fP, \fBpvmove\fP, +\fBlvchange\fP or \fBvgchange\fP LVM2 commands. + +The purpose of lvmpolld is to reduce the number of spawned background processes +per otherwise unique polling operation. There should be only one. It also +eliminates the possibility of unsolicited termination of background process by +external factors. + +lvmpolld is used by LVM only if it is enabled in \fBlvm.conf\fP(5) by +specifying the \fBglobal/use_lvmpolld\fP setting. If this is not defined in the +LVM configuration explicitly then default setting is used instead (see the +output of \fBlvmconfig \-\-type default global/use_lvmpolld\fP command). +.SH OPTIONS + +To run the daemon in a test environment both the pidfile_path and the +socket_path should be changed from the defaults. +.TP +.BR \-f ", " \-\-foreground +Don't fork, but run in the foreground. +.TP +.BR \-h ", " \-\-help +Show help information. +.TP +.IR \fB\-l\fP ", " \fB\-\-log\fP " {" all | wire | debug } +Select the type of log messages to generate. +Messages are logged by syslog. +Additionally, when \-f is given they are also sent to standard error. +There are two classes of messages: wire and debug. Selecting 'all' supplies both +and is equivalent to a comma-separated list \-l wire,debug. +.TP +.BR \-p ", " \-\-pidfile " " \fIpidfile_path +Path to the pidfile. This overrides both the built-in default +(#DEFAULT_PID_DIR#/lvmpolld.pid) and the environment variable +\fBLVM_LVMPOLLD_PIDFILE\fP. This file is used to prevent more +than one instance of the daemon running simultaneously. +.TP +.BR \-s ", " \-\-socket " " \fIsocket_path +Path to the socket file. This overrides both the built-in default +(#DEFAULT_RUN_DIR#/lvmpolld.socket) and the environment variable +\fBLVM_LVMPOLLD_SOCKET\fP. +.TP +.BR \-t ", " \-\-timeout " " \fItimeout_value +The daemon may shutdown after being idle for the given time (in seconds). When the +option is omitted or the value given is zero the daemon never shutdowns on idle. +.TP +.BR \-B ", " \-\-binary " " \fIlvm_binary_path +Optional path to alternative LVM binary (default: #LVM_PATH#). Use for +testing purposes only. +.TP +.BR \-V ", " \-\-version +Display the version of lvmpolld daemon. +.TP +.B \-\-dump +Contact the running lvmpolld daemon to obtain the complete state and print it +out in a raw format. +.SH ENVIRONMENT VARIABLES +.TP +.B LVM_LVMPOLLD_PIDFILE +Path for the pid file. +.TP +.B LVM_LVMPOLLD_SOCKET +Path for the socket file. + +.SH SEE ALSO +.BR lvm (8), +.BR lvm.conf (5) diff --git a/man/lvmraid.7.in b/man/lvmraid.7.in deleted file mode 100644 index dc07f2e..0000000 --- a/man/lvmraid.7.in +++ /dev/null @@ -1,1711 +0,0 @@ -.TH "LVMRAID" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" - -.SH NAME -lvmraid \(em LVM RAID - -.SH DESCRIPTION - -LVM RAID is a way to create logical volumes (LVs) that use multiple physical -devices to improve performance or tolerate device failure. How blocks of -data in an LV are placed onto physical devices is determined by the RAID -level. RAID levels are commonly referred to by number, e.g. raid1, raid5. -Selecting a RAID level involves tradeoffs among physical device -requirements, fault tolerance, and performance. A description of the RAID -levels can be found at -.br -www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf - -LVM RAID uses both Device Mapper (DM) and Multiple Device (MD) drivers -from the Linux kernel. DM is used to create and manage visible LVM -devices, and MD is used to place data on physical devices. - -LVM creates hidden LVs (dm devices) layered between the visible LV and -physical devices. LVs in that middle layers are called sub LVs. -For LVM raid, a sub LV pair to store data and metadata (raid superblock -and bitmap) is created per raid image/leg (see lvs command examples below). - -.SH Create a RAID LV - -To create a RAID LV, use lvcreate and specify an LV type. -The LV type corresponds to a RAID level. -The basic RAID levels that can be used are: -.B raid0, raid1, raid4, raid5, raid6, raid10. - -.B lvcreate \-\-type -.I RaidLevel -[\fIOPTIONS\fP] -.B \-\-name -.I Name -.B \-\-size -.I Size -.I VG -[\fIPVs\fP] - -To display the LV type of an existing LV, run: - -.B lvs -o name,segtype -\fIVG\fP/\fILV\fP - -(The LV type is also referred to as "segment type" or "segtype".) - -LVs can be created with the following types: - -.SS raid0 - -\& - -Also called striping, raid0 spreads LV data across multiple devices in -units of stripe size. This is used to increase performance. LV data will -be lost if any of the devices fail. - -.B lvcreate \-\-type raid0 -[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] -\fIVG\fP -[\fIPVs\fP] - -.HP -.B \-\-stripes -specifies the number of devices to spread the LV across. - -.HP -.B \-\-stripesize -specifies the size of each stripe in kilobytes. This is the amount of -data that is written to one device before moving to the next. -.P - -\fIPVs\fP specifies the devices to use. If not specified, lvm will choose -\fINumber\fP devices, one for each stripe. - -.SS raid1 - -\& - -Also called mirroring, raid1 uses multiple devices to duplicate LV data. -The LV data remains available if all but one of the devices fail. -The minimum number of devices (i.e. sub LV pairs) required is 2. - -.B lvcreate \-\-type raid1 -[\fB\-\-mirrors\fP \fINumber\fP] -\fIVG\fP -[\fIPVs\fP] - -.HP -.B \-\-mirrors -specifies the number of mirror images in addition to the original LV -image, e.g. \-\-mirrors 1 means there are two images of the data, the -original and one mirror image. -.P - -\fIPVs\fP specifies the devices to use. If not specified, lvm will choose -\fINumber\fP devices, one for each image. - -.SS raid4 - -\& - -raid4 is a form of striping that uses an extra, first device dedicated to -storing parity blocks. The LV data remains available if one device fails. The -parity is used to recalculate data that is lost from a single device. The -minimum number of devices required is 3. - -.B lvcreate \-\-type raid4 -[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] -\fIVG\fP -[\fIPVs\fP] - -.HP -.B \-\-stripes -specifies the number of devices to use for LV data. This does not include -the extra device lvm adds for storing parity blocks. \fINumber\fP stripes -requires \fINumber\fP+1 devices. \fINumber\fP must be 2 or more. - -.HP -.B \-\-stripesize -specifies the size of each stripe in kilobytes. This is the amount of -data that is written to one device before moving to the next. -.P - -\fIPVs\fP specifies the devices to use. If not specified, lvm will choose -\fINumber\fP+1 separate devices. - -raid4 is called non-rotating parity because the parity blocks are always -stored on the same device. - -.SS raid5 - -\& - -raid5 is a form of striping that uses an extra device for storing parity -blocks. LV data and parity blocks are stored on each device, typically in -a rotating pattern for performance reasons. The LV data remains available -if one device fails. The parity is used to recalculate data that is lost -from a single device. The minimum number of devices required is 3. - -.B lvcreate \-\-type raid5 -[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] -\fIVG\fP -[\fIPVs\fP] - -.HP -.B \-\-stripes -specifies the number of devices to use for LV data. This does not include -the extra device lvm adds for storing parity blocks. \fINumber\fP stripes -requires \fINumber\fP+1 devices. \fINumber\fP must be 2 or more. - -.HP -.B \-\-stripesize -specifies the size of each stripe in kilobytes. This is the amount of -data that is written to one device before moving to the next. -.P - -\fIPVs\fP specifies the devices to use. If not specified, lvm will choose -\fINumber\fP+1 separate devices. - -raid5 is called rotating parity because the parity blocks are placed on -different devices in a round-robin sequence. There are variations of -raid5 with different algorithms for placing the parity blocks. The -default variant is raid5_ls (raid5 left symmetric, which is a rotating -parity 0 with data restart.) See \fBRAID5 variants\fP below. - -.SS raid6 - -\& - -raid6 is a form of striping like raid5, but uses two extra devices for -parity blocks. LV data and parity blocks are stored on each device, typically -in a rotating pattern for perfomramce reasons. The -LV data remains available if up to two devices fail. The parity is used -to recalculate data that is lost from one or two devices. The minimum -number of devices required is 5. - -.B lvcreate \-\-type raid6 -[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] -\fIVG\fP -[\fIPVs\fP] - -.HP -.B \-\-stripes -specifies the number of devices to use for LV data. This does not include -the extra two devices lvm adds for storing parity blocks. \fINumber\fP -stripes requires \fINumber\fP+2 devices. \fINumber\fP must be 3 or more. - -.HP -.B \-\-stripesize -specifies the size of each stripe in kilobytes. This is the amount of -data that is written to one device before moving to the next. -.P - -\fIPVs\fP specifies the devices to use. If not specified, lvm will choose -\fINumber\fP+2 separate devices. - -Like raid5, there are variations of raid6 with different algorithms for -placing the parity blocks. The default variant is raid6_zr (raid6 zero -restart, aka left symmetric, which is a rotating parity 0 with data -restart.) See \fBRAID6 variants\fP below. - -.SS raid10 - -\& - -raid10 is a combination of raid1 and raid0, striping data across mirrored -devices. LV data remains available if one or more devices remains in each -mirror set. The minimum number of devices required is 4. - -.B lvcreate \-\-type raid10 -.RS -[\fB\-\-mirrors\fP \fINumberMirrors\fP] -.br -[\fB\-\-stripes\fP \fINumberStripes\fP \fB\-\-stripesize\fP \fISize\fP] -.br -\fIVG\fP -[\fIPVs\fP] -.RE - -.HP -.B \-\-mirrors -specifies the number of mirror images within each stripe. e.g. -\-\-mirrors 1 means there are two images of the data, the original and one -mirror image. - -.HP -.B \-\-stripes -specifies the total number of devices to use in all raid1 images (not the -number of raid1 devices to spread the LV across, even though that is the -effective result). The number of devices in each raid1 mirror will be -NumberStripes/(NumberMirrors+1), e.g. mirrors 1 and stripes 4 will stripe -data across two raid1 mirrors, where each mirror is devices. - -.HP -.B \-\-stripesize -specifies the size of each stripe in kilobytes. This is the amount of -data that is written to one device before moving to the next. -.P - -\fIPVs\fP specifies the devices to use. If not specified, lvm will choose -the necessary devices. Devices are used to create mirrors in the -order listed, e.g. for mirrors 1, stripes 2, listing PV1 PV2 PV3 PV4 -results in mirrors PV1/PV2 and PV3/PV4. - -RAID10 is not mirroring on top of stripes, which would be RAID01, which is -less tolerant of device failures. - - -.SH Synchronization - -Synchronization makes all the devices in a RAID LV consistent with each -other. - -In a RAID1 LV, all mirror images should have the same data. When a new -mirror image is added, or a mirror image is missing data, then images need -to be synchronized. Data blocks are copied from an existing image to a -new or outdated image to make them match. - -In a RAID 4/5/6 LV, parity blocks and data blocks should match based on -the parity calculation. When the devices in a RAID LV change, the data -and parity blocks can become inconsistent and need to be synchronized. -Correct blocks are read, parity is calculated, and recalculated blocks are -written. - -The RAID implementation keeps track of which parts of a RAID LV are -synchronized. This uses a bitmap saved in the RAID metadata. The bitmap -can exclude large parts of the LV from synchronization to reduce the -amount of work. Without this, the entire LV would need to be synchronized -every time it was activated. When a RAID LV is first created and -activated the first synchronization is called initialization. - -Automatic synchronization happens when a RAID LV is activated, but it is -usually partial because the bitmaps reduce the areas that are checked. -A full sync may become necessary when devices in the RAID LV are changed. - -The synchronization status of a RAID LV is reported by the -following command, where "image synced" means sync is complete: - -.B lvs -a -o name,sync_percent - - -.SS Scrubbing - -Scrubbing is a full scan/synchronization of the RAID LV requested by a user. -Scrubbing can find problems that are missed by partial synchronization. - -Scrubbing assumes that RAID metadata and bitmaps may be inaccurate, so it -verifies all RAID metadata, LV data, and parity blocks. Scrubbing can -find inconsistencies caused by hardware errors or degradation. These -kinds of problems may be undetected by automatic synchronization which -excludes areas outside of the RAID write-intent bitmap. - -The command to scrub a RAID LV can operate in two different modes: - -.B lvchange \-\-syncaction -.BR check | repair -.IR VG / LV - -.HP -.B check -Check mode is read\-only and only detects inconsistent areas in the RAID -LV, it does not correct them. - -.HP -.B repair -Repair mode checks and writes corrected blocks to synchronize any -inconsistent areas. - -.P - -Scrubbing can consume a lot of bandwidth and slow down application I/O on -the RAID LV. To control the I/O rate used for scrubbing, use: - -.HP -.B \-\-maxrecoveryrate -.BR \fIRate [ b | B | s | S | k | K | m | M | g | G ] -.br -Sets the maximum recovery rate for a RAID LV. \fIRate\fP is specified as -an amount per second for each device in the array. If no suffix is given, -then KiB/sec/device is assumed. Setting the recovery rate to \fB0\fP -means it will be unbounded. - -.HP -.BR \-\-minrecoveryrate -.BR \fIRate [ b | B | s | S | k | K | m | M | g | G ] -.br -Sets the minimum recovery rate for a RAID LV. \fIRate\fP is specified as -an amount per second for each device in the array. If no suffix is given, -then KiB/sec/device is assumed. Setting the recovery rate to \fB0\fP -means it will be unbounded. - -.P - -To display the current scrubbing in progress on an LV, including -the syncaction mode and percent complete, run: - -.B lvs -a -o name,raid_sync_action,sync_percent - -After scrubbing is complete, to display the number of inconsistent blocks -found, run: - -.B lvs -o name,raid_mismatch_count - -Also, if mismatches were found, the lvs attr field will display the letter -"m" (mismatch) in the 9th position, e.g. - -.nf -# lvs -o name,vgname,segtype,attr vg/lvol0 - LV VG Type Attr - lvol0 vg raid1 Rwi-a-r-m- -.fi - - -.SS Scrubbing Limitations - -The \fBcheck\fP mode can only report the number of inconsistent blocks, it -cannot report which blocks are inconsistent. This makes it impossible to -know which device has errors, or if the errors affect file system data, -metadata or nothing at all. - -The \fBrepair\fP mode can make the RAID LV data consistent, but it does -not know which data is correct. The result may be consistent but -incorrect data. When two different blocks of data must be made -consistent, it chooses the block from the device that would be used during -RAID intialization. However, if the PV holding corrupt data is known, -lvchange \-\-rebuild can be used to reconstruct the data on the bad -device. - -Future developments might include: - -Allowing a user to choose the correct version of data during repair. - -Using a majority of devices to determine the correct version of data to -use in a three-way RAID1 or RAID6 LV. - -Using a checksumming device to pin-point when and where an error occurs, -allowing it to be rewritten. - - -.SH SubLVs - -An LV is often a combination of other hidden LVs called SubLVs. The -SubLVs either use physical devices, or are built from other SubLVs -themselves. SubLVs hold LV data blocks, RAID parity blocks, and RAID -metadata. SubLVs are generally hidden, so the lvs \-a option is required -display them: - -.B lvs -a -o name,segtype,devices - -SubLV names begin with the visible LV name, and have an automatic suffix -indicating its role: - -.IP \(bu 3 -SubLVs holding LV data or parity blocks have the suffix _rimage_#. -These SubLVs are sometimes referred to as DataLVs. - -.IP \(bu 3 -SubLVs holding RAID metadata have the suffix _rmeta_#. RAID metadata -includes superblock information, RAID type, bitmap, and device health -information. These SubLVs are sometimes referred to as MetaLVs. - -.P - -SubLVs are an internal implementation detail of LVM. The way they are -used, constructed and named may change. - -The following examples show the SubLV arrangement for each of the basic -RAID LV types, using the fewest number of devices allowed for each. - -.SS Examples - -.B raid0 -.br -Each rimage SubLV holds a portion of LV data. No parity is used. -No RAID metadata is used. - -.nf -lvcreate --type raid0 --stripes 2 --name lvr0 ... - -lvs -a -o name,segtype,devices - lvr0 raid0 lvr0_rimage_0(0),lvr0_rimage_1(0) - [lvr0_rimage_0] linear /dev/sda(...) - [lvr0_rimage_1] linear /dev/sdb(...) -.fi - -.B raid1 -.br -Each rimage SubLV holds a complete copy of LV data. No parity is used. -Each rmeta SubLV holds RAID metadata. - -.nf -lvcreate --type raid1 --mirrors 1 --name lvr1 ... - -lvs -a -o name,segtype,devices - lvr1 raid1 lvr1_rimage_0(0),lvr1_rimage_1(0) - [lvr1_rimage_0] linear /dev/sda(...) - [lvr1_rimage_1] linear /dev/sdb(...) - [lvr1_rmeta_0] linear /dev/sda(...) - [lvr1_rmeta_1] linear /dev/sdb(...) -.fi - -.B raid4 -.br -Two rimage SubLVs each hold a portion of LV data and one rimage SubLV -holds parity. Each rmeta SubLV holds RAID metadata. - -.nf -lvcreate --type raid4 --stripes 2 --name lvr4 ... - -lvs -a -o name,segtype,devices - lvr4 raid4 lvr4_rimage_0(0),\\ - lvr4_rimage_1(0),\\ - lvr4_rimage_2(0) - [lvr4_rimage_0] linear /dev/sda(...) - [lvr4_rimage_1] linear /dev/sdb(...) - [lvr4_rimage_2] linear /dev/sdc(...) - [lvr4_rmeta_0] linear /dev/sda(...) - [lvr4_rmeta_1] linear /dev/sdb(...) - [lvr4_rmeta_2] linear /dev/sdc(...) -.fi - -.B raid5 -.br -Three rimage SubLVs each hold a portion of LV data and parity. -Each rmeta SubLV holds RAID metadata. - -.nf -lvcreate --type raid5 --stripes 2 --name lvr5 ... - -lvs -a -o name,segtype,devices - lvr5 raid5 lvr5_rimage_0(0),\\ - lvr5_rimage_1(0),\\ - lvr5_rimage_2(0) - [lvr5_rimage_0] linear /dev/sda(...) - [lvr5_rimage_1] linear /dev/sdb(...) - [lvr5_rimage_2] linear /dev/sdc(...) - [lvr5_rmeta_0] linear /dev/sda(...) - [lvr5_rmeta_1] linear /dev/sdb(...) - [lvr5_rmeta_2] linear /dev/sdc(...) -.fi - -.B raid6 -.br -Six rimage SubLVs each hold a portion of LV data and parity. -Each rmeta SubLV holds RAID metadata. - -.nf -lvcreate --type raid6 --stripes 3 --name lvr6 - -lvs -a -o name,segtype,devices - lvr6 raid6 lvr6_rimage_0(0),\\ - lvr6_rimage_1(0),\\ - lvr6_rimage_2(0),\\ - lvr6_rimage_3(0),\\ - lvr6_rimage_4(0),\\ - lvr6_rimage_5(0) - [lvr6_rimage_0] linear /dev/sda(...) - [lvr6_rimage_1] linear /dev/sdb(...) - [lvr6_rimage_2] linear /dev/sdc(...) - [lvr6_rimage_3] linear /dev/sdd(...) - [lvr6_rimage_4] linear /dev/sde(...) - [lvr6_rimage_5] linear /dev/sdf(...) - [lvr6_rmeta_0] linear /dev/sda(...) - [lvr6_rmeta_1] linear /dev/sdb(...) - [lvr6_rmeta_2] linear /dev/sdc(...) - [lvr6_rmeta_3] linear /dev/sdd(...) - [lvr6_rmeta_4] linear /dev/sde(...) - [lvr6_rmeta_5] linear /dev/sdf(...) - -.B raid10 -.br -Four rimage SubLVs each hold a portion of LV data. No parity is used. -Each rmeta SubLV holds RAID metadata. - -.nf -lvcreate --type raid10 --stripes 2 --mirrors 1 --name lvr10 - -lvs -a -o name,segtype,devices - lvr10 raid10 lvr10_rimage_0(0),\\ - lvr10_rimage_1(0),\\ - lvr10_rimage_2(0),\\ - lvr10_rimage_3(0) - [lvr10_rimage_0] linear /dev/sda(...) - [lvr10_rimage_1] linear /dev/sdb(...) - [lvr10_rimage_2] linear /dev/sdc(...) - [lvr10_rimage_3] linear /dev/sdd(...) - [lvr10_rmeta_0] linear /dev/sda(...) - [lvr10_rmeta_1] linear /dev/sdb(...) - [lvr10_rmeta_2] linear /dev/sdc(...) - [lvr10_rmeta_3] linear /dev/sdd(...) -.fi - - -.SH Device Failure - -Physical devices in a RAID LV can fail or be lost for multiple reasons. -A device could be disconnected, permanently failed, or temporarily -disconnected. The purpose of RAID LVs (levels 1 and higher) is to -continue operating in a degraded mode, without losing LV data, even after -a device fails. The number of devices that can fail without the loss of -LV data depends on the RAID level: - -.IP \[bu] 3 -RAID0 (striped) LVs cannot tolerate losing any devices. LV data will be -lost if any devices fail. - -.IP \[bu] 3 -RAID1 LVs can tolerate losing all but one device without LV data loss. - -.IP \[bu] 3 -RAID4 and RAID5 LVs can tolerate losing one device without LV data loss. - -.IP \[bu] 3 -RAID6 LVs can tolerate losing two devices without LV data loss. - -.IP \[bu] 3 -RAID10 is variable, and depends on which devices are lost. It can -tolerate losing all but one device in a single raid1 mirror without -LV data loss. - -.P - -If a RAID LV is missing devices, or has other device-related problems, lvs -reports this in the health_status (and attr) fields: - -.B lvs -o name,lv_health_status - -.B partial -.br -Devices are missing from the LV. This is also indicated by the letter "p" -(partial) in the 9th position of the lvs attr field. - -.B refresh needed -.br -A device was temporarily missing but has returned. The LV needs to be -refreshed to use the device again (which will usually require -partial synchronization). This is also indicated by the letter "r" (refresh -needed) in the 9th position of the lvs attr field. See -\fBRefreshing an LV\fP. This could also indicate a problem with the -device, in which case it should be be replaced, see -\fBReplacing Devices\fP. - -.B mismatches exist -.br -See -.BR Scrubbing . - -Most commands will also print a warning if a device is missing, e.g. -.br -.nf -WARNING: Device for PV uItL3Z-wBME-DQy0-... not found or rejected ... -.fi - -This warning will go away if the device returns or is removed from the -VG (see \fBvgreduce \-\-removemissing\fP). - - -.SS Activating an LV with missing devices - -A RAID LV that is missing devices may be activated or not, depending on -the "activation mode" used in lvchange: - -.B lvchange \-ay \-\-activationmode -.RB { complete | degraded | partial } -.IR VG / LV - -.B complete -.br -The LV is only activated if all devices are present. - -.B degraded -.br -The LV is activated with missing devices if the RAID level can -tolerate the number of missing devices without LV data loss. - -.B partial -.br -The LV is always activated, even if portions of the LV data are missing -because of the missing device(s). This should only be used to perform -recovery or repair operations. - -.BR lvm.conf (5) -.B activation/activation_mode -.br -controls the activation mode when not specified by the command. - -The default value is printed by: -.nf -lvmconfig --type default activation/activation_mode -.fi - -.SS Replacing Devices - -Devices in a RAID LV can be replaced with other devices in the VG. When -replacing devices that are no longer visible on the system, use lvconvert -\-\-repair. When replacing devices that are still visible, use lvconvert -\-\-replace. The repair command will attempt to restore the same number -of data LVs that were previously in the LV. The replace option can be -repeated to replace multiple PVs. Replacement devices can be optionally -listed with either option. - -.B lvconvert \-\-repair -.IR VG / LV -[\fINewPVs\fP] - -.B lvconvert \-\-replace -\fIOldPV\fP -.IR VG / LV -[\fINewPV\fP] - -.B lvconvert -.B \-\-replace -\fIOldPV1\fP -.B \-\-replace -\fIOldPV2\fP -... -.IR VG / LV -[\fINewPVs\fP] - -New devices require synchronization with existing devices, see -.BR Synchronization . - -.SS Refreshing an LV - -Refreshing a RAID LV clears any transient device failures (device was -temporarily disconnected) and returns the LV to its fully redundant mode. -Restoring a device will usually require at least partial synchronization -(see \fBSynchronization\fP). Failure to clear a transient failure results -in the RAID LV operating in degraded mode until it is reactivated. Use -the lvchange command to refresh an LV: - -.B lvchange \-\-refresh -.IR VG / LV - -.nf -# lvs -o name,vgname,segtype,attr,size vg - LV VG Type Attr LSize - raid1 vg raid1 Rwi-a-r-r- 100.00g - -# lvchange --refresh vg/raid1 - -# lvs -o name,vgname,segtype,attr,size vg - LV VG Type Attr LSize - raid1 vg raid1 Rwi-a-r--- 100.00g -.fi - -.SS Automatic repair - -If a device in a RAID LV fails, device-mapper in the kernel notifies the -.BR dmeventd (8) -monitoring process (see \fBMonitoring\fP). -dmeventd can be configured to automatically respond using: - -.BR lvm.conf (5) -.B activation/raid_fault_policy - -Possible settings are: - -.B warn -.br -A warning is added to the system log indicating that a device has -failed in the RAID LV. It is left to the user to repair the LV, e.g. -replace failed devices. - -.B allocate -.br -dmeventd automatically attempts to repair the LV using spare devices -in the VG. Note that even a transient failure is handled as a permanent -failure; a new device is allocated and full synchronization is started. - -The specific command run by dmeventd to warn or repair is: -.br -.B lvconvert \-\-repair \-\-use\-policies -.IR VG / LV - - -.SS Corrupted Data - -Data on a device can be corrupted due to hardware errors, without the -device ever being disconnected, and without any fault in the software. -This should be rare, and can be detected (see \fBScrubbing\fP). - - -.SS Rebuild specific PVs - -If specific PVs in a RAID LV are known to have corrupt data, the data on -those PVs can be reconstructed with: - -.B lvchange \-\-rebuild PV -.IR VG / LV - -The rebuild option can be repeated with different PVs to replace the data -on multiple PVs. - - -.SH Monitoring - -When a RAID LV is activated the \fBdmeventd\fP(8) process is started to -monitor the health of the LV. Various events detected in the kernel can -cause a notification to be sent from device-mapper to the monitoring -process, including device failures and synchronization completion (e.g. -for initialization or scrubbing). - -The LVM configuration file contains options that affect how the monitoring -process will respond to failure events (e.g. raid_fault_policy). It is -possible to turn on and off monitoring with lvchange, but it is not -recommended to turn this off unless you have a thorough knowledge of the -consequences. - - -.SH Configuration Options - -There are a number of options in the LVM configuration file that affect -the behavior of RAID LVs. The tunable options are listed -below. A detailed description of each can be found in the LVM -configuration file itself. -.br - mirror_segtype_default -.br - raid10_segtype_default -.br - raid_region_size -.br - raid_fault_policy -.br - activation_mode - - -.SH RAID1 Tuning - -A RAID1 LV can be tuned so that certain devices are avoided for reading -while all devices are still written to. - -.B lvchange -.BR \-\- [ raid ] writemostly -.BR \fIPhysicalVolume [ : { y | n | t }] -.IR VG / LV - -The specified device will be marked as "write mostly", which means that -reading from this device will be avoided, and other devices will be -preferred for reading (unless no other devices are available.) This -minimizes the I/O to the specified device. - -If the PV name has no suffix, the write mostly attribute is set. If the -PV name has the suffix \fB:n\fP, the write mostly attribute is cleared, -and the suffix \fB:t\fP toggles the current setting. - -The write mostly option can be repeated on the command line to change -multiple devices at once. - -To report the current write mostly setting, the lvs attr field will show -the letter "w" in the 9th position when write mostly is set: - -.B lvs -a -o name,attr - -When a device is marked write mostly, the maximum number of outstanding -writes to that device can be configured. Once the maximum is reached, -further writes become synchronous. When synchronous, a write to the LV -will not complete until writes to all the mirror images are complete. - -.B lvchange -.BR \-\- [ raid ] writebehind -.IR IOCount -.IR VG / LV - -To report the current write behind setting, run: - -.B lvs -o name,raid_write_behind - -When write behind is not configured, or set to 0, all LV writes are -synchronous. - - -.SH RAID Takeover - -RAID takeover is converting a RAID LV from one RAID level to another, e.g. -raid5 to raid6. Changing the RAID level is usually done to increase or -decrease resilience to device failures. This is done using lvconvert and -specifying the new RAID level as the LV type: - -.B lvconvert --type -.I RaidLevel -\fIVG\fP/\fILV\fP -[\fIPVs\fP] - -The most common and recommended RAID takeover conversions are: - -.HP -\fBlinear\fP to \fBraid1\fP -.br -Linear is a single image of LV data, and -converting it to raid1 adds a mirror image which is a direct copy of the -original linear image. - -.HP -\fBstriped\fP/\fBraid0\fP to \fBraid4/5/6\fP -.br -Adding parity devices to a -striped volume results in raid4/5/6. - -.P - -Unnatural conversions that are not recommended include converting between -striped and non-striped types. This is because file systems often -optimize I/O patterns based on device striping values. If those values -change, it can decrease performance. - -Converting to a higher RAID level requires allocating new SubLVs to hold -RAID metadata, and new SubLVs to hold parity blocks for LV data. -Converting to a lower RAID level removes the SubLVs that are no longer -needed. - -Conversion often requires full synchronization of the RAID LV (see -\fBSynchronization\fP). Converting to RAID1 requires copying all LV data -blocks to a new image on a new device. Converting to a parity RAID level -requires reading all LV data blocks, calculating parity, and writing the -new parity blocks. Synchronization can take a long time and degrade -performance (rate controls also apply to conversion, see -\fB\-\-maxrecoveryrate\fP.) - -Warning: though it is possible to create \fBstriped\fP LVs with up to 128 stripes, -a maximum of 64 stripes can be converted to \fBraid0\fP, 63 to \fBraid4/5\fP and -62 to \fBraid6\fP because of the added parity SubLVs. -A \fBstriped\fP LV with a maximum of 32 stripes can be converted to \fBraid10\fP. - -.P - -The following takeover conversions are currently possible: -.br -.IP \(bu 3 -between striped and raid0. -.IP \(bu 3 -between linear and raid1. -.IP \(bu 3 -between mirror and raid1. -.IP \(bu 3 -between 2-legged raid1 and raid4/5. -.IP \(bu 3 -between striped/raid0 and raid4. -.IP \(bu 3 -between striped/raid0 and raid5. -.IP \(bu 3 -between striped/raid0 and raid6. -.IP \(bu 3 -between raid4 and raid5. -.IP \(bu 3 -between raid4/raid5 and raid6. -.IP \(bu 3 -between striped/raid0 and raid10. - -.SS Examples - -1. Converting an LV from \fBlinear\fP to \fBraid1\fP. - -.nf -# lvs -a -o name,segtype,size vg - LV Type LSize - lv linear 300.00g - -# lvconvert --type raid1 --mirrors 1 vg/lv - -# lvs -a -o name,segtype,size vg - LV Type LSize - lv raid1 300.00g - [lv_rimage_0] linear 300.00g - [lv_rimage_1] linear 300.00g - [lv_rmeta_0] linear 3.00m - [lv_rmeta_1] linear 3.00m -.fi - -2. Converting an LV from \fBmirror\fP to \fBraid1\fP. - -.nf -# lvs -a -o name,segtype,size vg - LV Type LSize - lv mirror 100.00g - [lv_mimage_0] linear 100.00g - [lv_mimage_1] linear 100.00g - [lv_mlog] linear 3.00m -.IP \(bu 3 -between striped and raid4. - -.SS Examples - -1. Converting an LV from \fBlinear\fP to \fBraid1\fP. - -.nf -# lvs -a -o name,segtype,size vg - LV Type LSize - lv linear 300.00g - -# lvconvert --type raid1 --mirrors 1 vg/lv - -# lvs -a -o name,segtype,size vg - LV Type LSize - lv raid1 300.00g - [lv_rimage_0] linear 300.00g - [lv_rimage_1] linear 300.00g - [lv_rmeta_0] linear 3.00m - [lv_rmeta_1] linear 3.00m -.fi - -2. Converting an LV from \fBmirror\fP to \fBraid1\fP. - -.nf -# lvs -a -o name,segtype,size vg - LV Type LSize - lv mirror 100.00g - [lv_mimage_0] linear 100.00g - [lv_mimage_1] linear 100.00g - [lv_mlog] linear 3.00m - -# lvconvert --type raid1 vg/lv - -# lvs -a -o name,segtype,size vg - LV Type LSize - lv raid1 100.00g - [lv_rimage_0] linear 100.00g - [lv_rimage_1] linear 100.00g - [lv_rmeta_0] linear 3.00m - [lv_rmeta_1] linear 3.00m -.fi - -3. Converting an LV from \fBlinear\fP to \fBraid1\fP (with 3 images). - -.nf -Start with a linear LV: - -# lvcreate -L1G -n lv vg - -Convert the linear LV to raid1 with three images -(original linear image plus 2 mirror images): - -# lvconvert --type raid1 --mirrors 2 vg/lv -.fi - -4. Converting an LV from \fBstriped\fP (with 4 stripes) to \fBraid6_nc\fP. - -.nf -Start with a striped LV: - -# lvcreate --stripes 4 -L64M -n lv vg - -Convert the striped LV to raid6_n_6: - -# lvconvert --type raid6 vg/lv - -# lvs -a -o lv_name,segtype,sync_percent,data_copies - LV Type Cpy%Sync #Cpy - lv raid6_n_6 100.00 3 - [lv_rimage_0] linear - [lv_rimage_1] linear - [lv_rimage_2] linear - [lv_rimage_3] linear - [lv_rimage_4] linear - [lv_rimage_5] linear - [lv_rmeta_0] linear - [lv_rmeta_1] linear - [lv_rmeta_2] linear - [lv_rmeta_3] linear - [lv_rmeta_4] linear - [lv_rmeta_5] linear -.fi - -This convert begins by allocating MetaLVs (rmeta_#) for each of the -existing stripe devices. It then creates 2 additional MetaLV/DataLV pairs -(rmeta_#/rimage_#) for dedicated raid6 parity. - -If rotating data/parity is required, such as with raid6_nr, it must be -done by reshaping (see below). - - -.SH RAID Reshaping - -RAID reshaping is changing attributes of a RAID LV while keeping the same -RAID level. This includes changing RAID layout, stripe size, or number of -stripes. - -When changing the RAID layout or stripe size, no new SubLVs (MetaLVs or -DataLVs) need to be allocated, but DataLVs are extended by a small amount -(typically 1 extent). The extra space allows blocks in a stripe to be -updated safely, and not corrupted in case of a crash. If a crash occurs, -reshaping can just be restarted. - -(If blocks in a stripe were updated in place, a crash could leave them -partially updated and corrupted. Instead, an existing stripe is quiesced, -read, changed in layout, and the new stripe written to free space. Once -that is done, the new stripe is unquiesced and used.) - -.SS Examples - -1. Converting raid6_n_6 to raid6_nr with rotating data/parity. - -This conversion naturally follows a previous conversion from striped/raid0 -to raid6_n_6 (shown above). It completes the transition to a more -traditional RAID6. - -.nf -# lvs -o lv_name,segtype,sync_percent,data_copies - LV Type Cpy%Sync #Cpy - lv raid6_n_6 100.00 3 - [lv_rimage_0] linear - [lv_rimage_1] linear - [lv_rimage_2] linear - [lv_rimage_3] linear - [lv_rimage_4] linear - [lv_rimage_5] linear - [lv_rmeta_0] linear - [lv_rmeta_1] linear - [lv_rmeta_2] linear - [lv_rmeta_3] linear - [lv_rmeta_4] linear - [lv_rmeta_5] linear - -# lvconvert --type raid6_nr vg/lv - -# lvs -a -o lv_name,segtype,sync_percent,data_copies - LV Type Cpy%Sync #Cpy - lv raid6_nr 100.00 3 - [lv_rimage_0] linear - [lv_rimage_0] linear - [lv_rimage_1] linear - [lv_rimage_1] linear - [lv_rimage_2] linear - [lv_rimage_2] linear - [lv_rimage_3] linear - [lv_rimage_3] linear - [lv_rimage_4] linear - [lv_rimage_5] linear - [lv_rmeta_0] linear - [lv_rmeta_1] linear - [lv_rmeta_2] linear - [lv_rmeta_3] linear - [lv_rmeta_4] linear - [lv_rmeta_5] linear -.fi - -The DataLVs are larger (additional segment in each) which provides space -for out-of-place reshaping. The result is: - -.nf -# lvs -a -o lv_name,segtype,seg_pe_ranges,dataoffset - LV Type PE Ranges DOff - lv raid6_nr lv_rimage_0:0-32 \\ - lv_rimage_1:0-32 \\ - lv_rimage_2:0-32 \\ - lv_rimage_3:0-32 - [lv_rimage_0] linear /dev/sda:0-31 2048 - [lv_rimage_0] linear /dev/sda:33-33 - [lv_rimage_1] linear /dev/sdaa:0-31 2048 - [lv_rimage_1] linear /dev/sdaa:33-33 - [lv_rimage_2] linear /dev/sdab:1-33 2048 - [lv_rimage_3] linear /dev/sdac:1-33 2048 - [lv_rmeta_0] linear /dev/sda:32-32 - [lv_rmeta_1] linear /dev/sdaa:32-32 - [lv_rmeta_2] linear /dev/sdab:0-0 - [lv_rmeta_3] linear /dev/sdac:0-0 -.fi - -All segments with PE ranges '33-33' provide the out-of-place reshape space. -The dataoffset column shows that the data was moved from initial offset 0 to -2048 sectors on each component DataLV. - -For performance reasons the raid6_nr RaidLV can be restriped. -Convert it from 3-way striped to 5-way-striped. - -.nf -# lvconvert --stripes 5 -y tb/lv - Using default stripesize 64.00 KiB. - WARNING: Adding stripes to active logical volume tb/lv will grow it from 99 to 165 extents! - Run "lvresize -l99 tb/lv" to shrink it or use the additional capacity. - Logical volume tb/lv successfully converted. - -# lvs - LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert - root fedora -wi-ao---- 15.00g - swap fedora -wi-ao---- 3.99g - lv tb rwi-a-r-s- 652.00m 52.94 - -# lvs -a -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb - LV Attr Type PE Ranges DOff - lv rwi-a-r--- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 lv_rimage_6:0-33 0 - [lv_rimage_0] iwi-aor--- linear /dev/sda:0-32 0 - [lv_rimage_0] iwi-aor--- linear /dev/sda:34-34 - [lv_rimage_1] iwi-aor--- linear /dev/sdaa:0-32 0 - [lv_rimage_1] iwi-aor--- linear /dev/sdaa:34-34 - [lv_rimage_2] iwi-aor--- linear /dev/sdab:0-32 0 - [lv_rimage_2] iwi-aor--- linear /dev/sdab:34-34 - [lv_rimage_3] iwi-aor--- linear /dev/sdac:1-34 0 - [lv_rimage_4] iwi-aor--- linear /dev/sdad:1-34 0 - [lv_rimage_5] iwi-aor--- linear /dev/sdae:1-34 0 - [lv_rimage_6] iwi-aor--- linear /dev/sdaf:1-34 0 - [lv_rmeta_0] ewi-aor--- linear /dev/sda:33-33 - [lv_rmeta_1] ewi-aor--- linear /dev/sdaa:33-33 - [lv_rmeta_2] ewi-aor--- linear /dev/sdab:33-33 - [lv_rmeta_3] ewi-aor--- linear /dev/sdac:0-0 - [lv_rmeta_4] ewi-aor--- linear /dev/sdad:0-0 - [lv_rmeta_5] ewi-aor--- linear /dev/sdae:0-0 - [lv_rmeta_6] ewi-aor--- linear /dev/sdaf:0-0 -.fi - -Stripes also can be removed from raid5 and 6. -Convert the 5-way striped raid6_nr LV to 4-way-striped. -The force option needs to be used, because removing stripes -(i.e. image SubLVs) from a RaidLV will shrink its size. - -.nf -# lvconvert --stripes 4 --force -y tb/lv - Using default stripesize 64.00 KiB. - WARNING: Removing stripes from active logical volume tb/lv will shrink it from 660.00 MiB to 528.00 MiB! - THIS MAY DESTROY (PARTS OF) YOUR DATA! - If that leaves the logical volume larger than 206 extents due to stripe rounding, - you may want to grow the content afterwards (filesystem etc.) - WARNING: too remove freed stripes after the conversion has finished, you have to run "lvconvert --stripes 4 tb/lv" - Logical volume tb/lv successfully converted. - -# lvs -a -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb - LV Attr Type PE Ranges DOff - lv rwi-a-r-s- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 lv_rimage_6:0-33 0 - [lv_rimage_0] Iwi-aor--- linear /dev/sda:0-32 0 - [lv_rimage_0] Iwi-aor--- linear /dev/sda:34-34 - [lv_rimage_1] Iwi-aor--- linear /dev/sdaa:0-32 0 - [lv_rimage_1] Iwi-aor--- linear /dev/sdaa:34-34 - [lv_rimage_2] Iwi-aor--- linear /dev/sdab:0-32 0 - [lv_rimage_2] Iwi-aor--- linear /dev/sdab:34-34 - [lv_rimage_3] Iwi-aor--- linear /dev/sdac:1-34 0 - [lv_rimage_4] Iwi-aor--- linear /dev/sdad:1-34 0 - [lv_rimage_5] Iwi-aor--- linear /dev/sdae:1-34 0 - [lv_rimage_6] Iwi-aor-R- linear /dev/sdaf:1-34 0 - [lv_rmeta_0] ewi-aor--- linear /dev/sda:33-33 - [lv_rmeta_1] ewi-aor--- linear /dev/sdaa:33-33 - [lv_rmeta_2] ewi-aor--- linear /dev/sdab:33-33 - [lv_rmeta_3] ewi-aor--- linear /dev/sdac:0-0 - [lv_rmeta_4] ewi-aor--- linear /dev/sdad:0-0 - [lv_rmeta_5] ewi-aor--- linear /dev/sdae:0-0 - [lv_rmeta_6] ewi-aor-R- linear /dev/sdaf:0-0 -.fi - -The 's' in column 9 of the attribute field shows the RaidLV is still reshaping. -The 'R' in the same column of the attribute field shows the freed image Sub LVs which will need removing once the reshaping finished. - -.nf -# lvs -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb - LV Attr Type PE Ranges DOff - lv rwi-a-r-R- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 lv_rimage_6:0-33 8192 -.fi - -Now that the reshape is finished the 'R' atribute on the RaidLV shows images can be removed. - -.nf -# lvs -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb - LV Attr Type PE Ranges DOff - lv rwi-a-r-R- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 lv_rimage_6:0-33 8192 -.fi - -This is achieved by repeating the command ("lvconvert --stripes 4 tb/lv" would be sufficient). - -.nf -# lvconvert --stripes 4 --force -y tb/lv - Using default stripesize 64.00 KiB. - Logical volume tb/lv successfully converted. - -# lvs -a -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb - LV Attr Type PE Ranges DOff - lv rwi-a-r--- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 8192 - [lv_rimage_0] iwi-aor--- linear /dev/sda:0-32 8192 - [lv_rimage_0] iwi-aor--- linear /dev/sda:34-34 - [lv_rimage_1] iwi-aor--- linear /dev/sdaa:0-32 8192 - [lv_rimage_1] iwi-aor--- linear /dev/sdaa:34-34 - [lv_rimage_2] iwi-aor--- linear /dev/sdab:0-32 8192 - [lv_rimage_2] iwi-aor--- linear /dev/sdab:34-34 - [lv_rimage_3] iwi-aor--- linear /dev/sdac:1-34 8192 - [lv_rimage_4] iwi-aor--- linear /dev/sdad:1-34 8192 - [lv_rimage_5] iwi-aor--- linear /dev/sdae:1-34 8192 - [lv_rmeta_0] ewi-aor--- linear /dev/sda:33-33 - [lv_rmeta_1] ewi-aor--- linear /dev/sdaa:33-33 - [lv_rmeta_2] ewi-aor--- linear /dev/sdab:33-33 - [lv_rmeta_3] ewi-aor--- linear /dev/sdac:0-0 - [lv_rmeta_4] ewi-aor--- linear /dev/sdad:0-0 - [lv_rmeta_5] ewi-aor--- linear /dev/sdae:0-0 - -# lvs -a -o lv_name,attr,segtype,reshapelen tb - LV Attr Type RSize - lv rwi-a-r--- raid6_nr 24.00m - [lv_rimage_0] iwi-aor--- linear 4.00m - [lv_rimage_0] iwi-aor--- linear - [lv_rimage_1] iwi-aor--- linear 4.00m - [lv_rimage_1] iwi-aor--- linear - [lv_rimage_2] iwi-aor--- linear 4.00m - [lv_rimage_2] iwi-aor--- linear - [lv_rimage_3] iwi-aor--- linear 4.00m - [lv_rimage_4] iwi-aor--- linear 4.00m - [lv_rimage_5] iwi-aor--- linear 4.00m - [lv_rmeta_0] ewi-aor--- linear - [lv_rmeta_1] ewi-aor--- linear - [lv_rmeta_2] ewi-aor--- linear - [lv_rmeta_3] ewi-aor--- linear - [lv_rmeta_4] ewi-aor--- linear - [lv_rmeta_5] ewi-aor--- linear -.fi - -If the reshape space shall be removed any lvconvert command not changing the layout can be used: - -.nf -# lvconvert --stripes 4 tb/lv - Using default stripesize 64.00 KiB. - No change in RAID LV tb/lv layout, freeing reshape space. - Logical volume tb/lv successfully converted. - -# lvs -a -o lv_name,attr,segtype,reshapelen tb - LV Attr Type RSize - lv rwi-a-r--- raid6_nr 0 - [lv_rimage_0] iwi-aor--- linear 0 - [lv_rimage_0] iwi-aor--- linear - [lv_rimage_1] iwi-aor--- linear 0 - [lv_rimage_1] iwi-aor--- linear - [lv_rimage_2] iwi-aor--- linear 0 - [lv_rimage_2] iwi-aor--- linear - [lv_rimage_3] iwi-aor--- linear 0 - [lv_rimage_4] iwi-aor--- linear 0 - [lv_rimage_5] iwi-aor--- linear 0 - [lv_rmeta_0] ewi-aor--- linear - [lv_rmeta_1] ewi-aor--- linear - [lv_rmeta_2] ewi-aor--- linear - [lv_rmeta_3] ewi-aor--- linear - [lv_rmeta_4] ewi-aor--- linear - [lv_rmeta_5] ewi-aor--- linear -.fi - -In case the RaidLV should be converted to striped: - -.nf -# lvconvert --type striped tb/lv - Unable to convert LV tb/lv from raid6_nr to striped. - Converting tb/lv from raid6_nr is directly possible to the following layouts: - raid6_nc - raid6_zr - raid6_la_6 - raid6_ls_6 - raid6_ra_6 - raid6_rs_6 - raid6_n_6 - -# lvconvert --type raid6_n_6 - Using default stripesize 64.00 KiB. - Converting raid6_nr LV tb/lv to raid6_n_6. -Are you sure you want to convert raid6_nr LV tb/lv? [y/n]: y - Logical volume tb/lv successfully converted. - -# lvconvert -y --type striped tb/lv - Logical volume tb/lv successfully converted. - -[root at vm46 ~]# lvs -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb - LV Attr Type PE Ranges DOff - lv -wi-a----- striped /dev/sda:2-32 /dev/sdaa:2-32 /dev/sdab:2-32 /dev/sdac:3-33 - lv -wi-a----- striped /dev/sda:34-35 /dev/sdaa:34-35 /dev/sdab:34-35 /dev/sdac:34-35 -.fi - -From striped we can convert to raid10 - -.nf -# lvconvert -y --type raid10 tb/lv - Using default stripesize 64.00 KiB. - Logical volume tb/lv successfully converted. - -# lvs -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb - LV Attr Type PE Ranges DOff - lv rwi-a-r--- raid10 lv_rimage_0:0-32 lv_rimage_4:0-32 lv_rimage_1:0-32 ... lv_rimage_3:0-32 lv_rimage_7:0-32 0 - -# lvs -a -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb - WARNING: Cannot find matching striped segment for tb/lv_rimage_3. - LV Attr Type PE Ranges DOff - lv rwi-a-r--- raid10 lv_rimage_0:0-32 lv_rimage_4:0-32 lv_rimage_1:0-32 ... lv_rimage_3:0-32 lv_rimage_7:0-32 0 - [lv_rimage_0] iwi-aor--- linear /dev/sda:2-32 0 - [lv_rimage_0] iwi-aor--- linear /dev/sda:34-35 - [lv_rimage_1] iwi-aor--- linear /dev/sdaa:2-32 0 - [lv_rimage_1] iwi-aor--- linear /dev/sdaa:34-35 - [lv_rimage_2] iwi-aor--- linear /dev/sdab:2-32 0 - [lv_rimage_2] iwi-aor--- linear /dev/sdab:34-35 - [lv_rimage_3] iwi-XXr--- linear /dev/sdac:3-35 0 - [lv_rimage_4] iwi-aor--- linear /dev/sdad:1-33 0 - [lv_rimage_5] iwi-aor--- linear /dev/sdae:1-33 0 - [lv_rimage_6] iwi-aor--- linear /dev/sdaf:1-33 0 - [lv_rimage_7] iwi-aor--- linear /dev/sdag:1-33 0 - [lv_rmeta_0] ewi-aor--- linear /dev/sda:0-0 - [lv_rmeta_1] ewi-aor--- linear /dev/sdaa:0-0 - [lv_rmeta_2] ewi-aor--- linear /dev/sdab:0-0 - [lv_rmeta_3] ewi-aor--- linear /dev/sdac:0-0 - [lv_rmeta_4] ewi-aor--- linear /dev/sdad:0-0 - [lv_rmeta_5] ewi-aor--- linear /dev/sdae:0-0 - [lv_rmeta_6] ewi-aor--- linear /dev/sdaf:0-0 - [lv_rmeta_7] ewi-aor--- linear /dev/sdag:0-0 -.fi - -raid10 allows to add stripes but can't remove them. - - -A more elaborate example to convert from linear to striped -with interim conversions to raid1 then raid5 followed -by restripe (4 steps). - -We start with the linear LV. - -.nf -# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg - LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices - lv -wi-a----- 128.00m linear 1 0 /dev/sda(0) -.fi - -Then convert it to a 2-way raid1. - -.nf -# lvconvert -m1 vg/lv - Logical volume vg/lv successfully converted. - -# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg - LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices - lv rwi-a-r--- 128.00m raid1 100.00 2 0 lv_rimage_0(0),lv_rimage_1(0) - [lv_rimage_0] iwi-aor--- 128.00m linear 1 0 /dev/sda(0) - [lv_rimage_1] iwi-aor--- 128.00m linear 1 0 /dev/sdhx(1) - [lv_rmeta_0] ewi-aor--- 4.00m linear 1 0 /dev/sda(32) - [lv_rmeta_1] ewi-aor--- 4.00m linear 1 0 /dev/sdhx(0) -.fi - -Once the raid1 LV is fully synchronized we convert it to raid5_n (only 2-way raid1 -LVs can be converted to raid5). We select raid5_n here because it has dedicated parity -SubLVs at the end and can be converted to striped directly without any additional -conversion. - -.nf -# lvconvert -y --ty raid5_n vg/lv - Using default stripesize 64.00 KiB. - Logical volume vg/lv successfully converted. - -# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg - LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices - lv rwi-a-r--- 128.00m raid5_n 100.00 1 64.00k 0 lv_rimage_0(0),lv_rimage_1(0) - [lv_rimage_0] iwi-aor--- 128.00m linear 1 0 0 /dev/sda(0) - [lv_rimage_1] iwi-aor--- 128.00m linear 1 0 0 /dev/sdhx(1) - [lv_rmeta_0] ewi-aor--- 4.00m linear 1 0 /dev/sda(32) - [lv_rmeta_1] ewi-aor--- 4.00m linear 1 0 /dev/sdhx(0) -.fi - -Now we'll change the number of data stripes from 1 to 5 and request 128K stripe size -in one command. This will grow the size of the LV by a factor of 5 (we add 4 data stripes -to the one given). That additonal space can be used by e.g. growing any contained filesystem -or the LV can be reduced in size after the reshaping conversion has finished. - -.nf -# lvconvert --yes --stripesize 128k --stripes 5 vg/lv - Converting stripesize 64.00 KiB of raid5_n LV vg/lv to 128.00 KiB. - WARNING: Adding stripes to active logical volume vg/lv will grow it from 32 to 160 extents! - Run "lvresize -l32 vg/lv" to shrink it or use the additional capacity. - Logical volume vg/lv successfully converted. - -# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg - LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices - lv rwi-a-r--- 640.00m raid5_n 100.00 5 128.00k 6 lv_rimage_0(0),lv_rimage_1(0),lv_rimage_2(0),lv_rimage_3(0),lv_rimage_4(0),lv_rimage_5(0) - [lv_rimage_0] iwi-aor--- 132.00m linear 1 0 1 /dev/sda(33) - [lv_rimage_0] iwi-aor--- 132.00m linear 1 0 /dev/sda(0) - [lv_rimage_1] iwi-aor--- 132.00m linear 1 0 1 /dev/sdhx(33) - [lv_rimage_1] iwi-aor--- 132.00m linear 1 0 /dev/sdhx(1) - [lv_rimage_2] iwi-aor--- 132.00m linear 1 0 1 /dev/sdhw(33) - [lv_rimage_2] iwi-aor--- 132.00m linear 1 0 /dev/sdhw(1) - [lv_rimage_3] iwi-aor--- 132.00m linear 1 0 1 /dev/sdhv(33) - [lv_rimage_3] iwi-aor--- 132.00m linear 1 0 /dev/sdhv(1) - [lv_rimage_4] iwi-aor--- 132.00m linear 1 0 1 /dev/sdhu(33) - [lv_rimage_4] iwi-aor--- 132.00m linear 1 0 /dev/sdhu(1) - [lv_rimage_5] iwi-aor--- 132.00m linear 1 0 1 /dev/sdht(33) - [lv_rimage_5] iwi-aor--- 132.00m linear 1 0 /dev/sdht(1) - [lv_rmeta_0] ewi-aor--- 4.00m linear 1 0 /dev/sda(32) - [lv_rmeta_1] ewi-aor--- 4.00m linear 1 0 /dev/sdhx(0) - [lv_rmeta_2] ewi-aor--- 4.00m linear 1 0 /dev/sdhw(0) - [lv_rmeta_3] ewi-aor--- 4.00m linear 1 0 /dev/sdhv(0) - [lv_rmeta_4] ewi-aor--- 4.00m linear 1 0 /dev/sdhu(0) - [lv_rmeta_5] ewi-aor--- 4.00m linear 1 0 /dev/sdht(0) -.fi - -Once the conversion has finished we can can convert to striped. - -.nf -[root at vm46 ~]# lvconvert -y --ty striped vg/lv - Logical volume vg/lv successfully converted. - -[root at vm46 ~]# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg|sed 's/ *$//' - LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices - lv -wi-a----- 640.00m striped 5 128.00k /dev/sda(33),/dev/sdhx(33),/dev/sdhw(33),/dev/sdhv(33),/dev/sdhu(33) - lv -wi-a----- 640.00m striped 5 128.00k /dev/sda(0),/dev/sdhx(1),/dev/sdhw(1),/dev/sdhv(1),/dev/sdhu(1) -.fi - -Reversing these steps wil convert a given striped LV to linear. - -Mind the fact that stripes are removed thus the capacity of the RaidLV will shrink. - -"lvconvert --stripes 1 vg/lv" for converting to 1 stripe will inform upfront about -the reduced size to allow for resizing the content or growing the RaidLV before -actually converting to 1 stripe. The \fB\-\-force\fP option is needed to -allow stripe removing conversions to prevent data loss. - -Of course any interim step can be the intended last one (e.g. striped -> raid1). -.. - -.SH RAID5 Variants - -raid5_ls -.br -\[bu] -RAID5 left symmetric -.br -\[bu] -Rotating parity N with data restart - -raid5_la -.br -\[bu] -RAID5 left symmetric -.br -\[bu] -Rotating parity N with data continuation - -raid5_rs -.br -\[bu] -RAID5 right symmetric -.br -\[bu] -Rotating parity 0 with data restart - -raid5_ra -.br -\[bu] -RAID5 right asymmetric -.br -\[bu] -Rotating parity 0 with data continuation - -raid5_n -.br -\[bu] -RAID5 parity n -.br -\[bu] -Dedicated parity device n used for striped/raid0 conversions -\[bu] -Used for RAID Takeover - -.SH RAID6 Variants - -raid6 -.br -\[bu] -RAID6 zero restart (aka left symmetric) -.br -\[bu] -Rotating parity 0 with data restart -.br -\[bu] -Same as raid6_zr - -raid6_zr -.br -\[bu] -RAID6 zero restart (aka left symmetric) -.br -\[bu] -Rotating parity 0 with data restart - -raid6_nr -.br -\[bu] -RAID6 N restart (aka right symmetric) -.br -\[bu] -Rotating parity N with data restart - -raid6_nc -.br -\[bu] -RAID6 N continue -.br -\[bu] -Rotating parity N with data continuation - -raid6_n_6 -.br -\[bu] -RAID6 last parity devices -.br -\[bu] -Dedicated last parity devices used for striped/raid0 conversions -\[bu] -Used for RAID Takeover - -raid6_{ls,rs,la,ra}_6 -.br -\[bu] -RAID6 last parity device -.br -\[bu] -Dedicated last parity device used for conversions from/to raid5_{ls,rs,la,ra} - -raid6_n_6 -.br -\[bu] -RAID6 N continue -.br -\[bu] -Fixed P-Syndrome N-1 and Q-Syndrome N with striped data -.br -\[bu] -Used for RAID Takeover - -raid6_ls_6 -.br -\[bu] -RAID6 N continue -.br -\[bu] -Same as raid5_ls for N-1 disks with fixed Q-Syndrome N -.br -\[bu] -Used for RAID Takeover - -raid6_la_6 -.br -\[bu] -RAID6 N continue -.br -\[bu] -Same as raid5_la for N-1 disks with fixed Q-Syndrome N -.br -\[bu] -Used forRAID Takeover - -raid6_rs_6 -.br -\[bu] -RAID6 N continue -.br -\[bu] -Same as raid5_rs for N-1 disks with fixed Q-Syndrome N -.br -\[bu] -Used for RAID Takeover - -raid6_ra_6 -.br -\[bu] -RAID6 N continue -.br -\[bu] -Same as raid5_ra for N-1 disks with fixed Q-Syndrome N -.br -\[bu] -Used for RAID Takeover - - -.ig -.SH RAID Duplication - -RAID LV conversion (takeover or reshaping) can be done out\-of\-place by -copying the LV data onto new devices while changing the RAID properties. -Copying avoids modifying the original LV but requires additional devices. -Once the LV data has been copied/converted onto the new devices, there are -multiple options: - -1. The RAID LV can be switched over to run from just the new devices, and -the original copy of the data removed. The converted LV then has the new -RAID properties, and exists on new devices. The old devices holding the -original data can be removed or reused. - -2. The new copy of the data can be dropped, leaving the original RAID LV -unchanged and using its original devices. - -3. The new copy of the data can be separated and used as a new independent -LV, leaving the original RAID LV unchanged on its original devices. - -The command to start duplication is: - -.B lvconvert \-\-type -.I RaidLevel -[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] -.RS -.B \-\-duplicate -.IR VG / LV -[\fIPVs\fP] -.RE - -.HP -.B \-\-duplicate -.br -Specifies that the LV conversion should be done out\-of\-place, copying -LV data to new devices while converting. - -.HP -.BR \-\-type , \-\-stripes , \-\-stripesize -.br -Specifies the RAID properties to use when creating the copy. - -.P -\fIPVs\fP specifies the new devices to use. - -The steps in the duplication process: - -.IP \(bu 3 -LVM creates a new LV on new devices using the specified RAID properties -(type, stripes, etc) and optionally specified devices. - -.IP \(bu 3 -LVM changes the visible RAID LV to type raid1, making the original LV the -first raid1 image (SubLV 0), and the new LV the second raid1 image -(SubLV 1). - -.IP \(bu 3 -The RAID1 synchronization process copies data from the original LV -image (SubLV 0) to the new LV image (SubLV 1). - -.IP \(bu 3 -When synchronization is complete, the original and new LVs are -mirror images of each other and can be separated. - -.P - -The duplication process retains both the original and new LVs (both -SubLVs) until an explicit unduplicate command is run to separate them. The -unduplicate command specifies if the original LV should use the old -devices (SubLV 0) or the new devices (SubLV 1). - -To make the RAID LV use the data on the old devices, and drop the copy on -the new devices, specify the name of SubLV 0 (suffix _dup_0): - -.B lvconvert \-\-unduplicate -.BI \-\-name -.IB LV _dup_0 -.IR VG / LV - -To make the RAID LV use the data copy on the new devices, and drop the old -devices, specify the name of SubLV 1 (suffix _dup_1): - -.B lvconvert \-\-unduplicate -.BI \-\-name -.IB LV _dup_1 -.IR VG / LV - -FIXME: To make the LV use the data on the original devices, but keep the -data copy as a new LV, ... - -FIXME: include how splitmirrors can be used. - - -.SH RAID1E - -TODO -.. - -.SH History - -The 2.6.38-rc1 version of the Linux kernel introduced a device-mapper -target to interface with the software RAID (MD) personalities. This -provided device-mapper with RAID 4/5/6 capabilities and a larger -development community. Later, support for RAID1, RAID10, and RAID1E (RAID -10 variants) were added. Support for these new kernel RAID targets was -added to LVM version 2.02.87. The capabilities of the LVM \fBraid1\fP -type have surpassed the old \fBmirror\fP type. raid1 is now recommended -instead of mirror. raid1 became the default for mirroring in LVM version -2.02.100. - diff --git a/man/lvmraid.7_main b/man/lvmraid.7_main new file mode 100644 index 0000000..dc07f2e --- /dev/null +++ b/man/lvmraid.7_main @@ -0,0 +1,1711 @@ +.TH "LVMRAID" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" + +.SH NAME +lvmraid \(em LVM RAID + +.SH DESCRIPTION + +LVM RAID is a way to create logical volumes (LVs) that use multiple physical +devices to improve performance or tolerate device failure. How blocks of +data in an LV are placed onto physical devices is determined by the RAID +level. RAID levels are commonly referred to by number, e.g. raid1, raid5. +Selecting a RAID level involves tradeoffs among physical device +requirements, fault tolerance, and performance. A description of the RAID +levels can be found at +.br +www.snia.org/sites/default/files/SNIA_DDF_Technical_Position_v2.0.pdf + +LVM RAID uses both Device Mapper (DM) and Multiple Device (MD) drivers +from the Linux kernel. DM is used to create and manage visible LVM +devices, and MD is used to place data on physical devices. + +LVM creates hidden LVs (dm devices) layered between the visible LV and +physical devices. LVs in that middle layers are called sub LVs. +For LVM raid, a sub LV pair to store data and metadata (raid superblock +and bitmap) is created per raid image/leg (see lvs command examples below). + +.SH Create a RAID LV + +To create a RAID LV, use lvcreate and specify an LV type. +The LV type corresponds to a RAID level. +The basic RAID levels that can be used are: +.B raid0, raid1, raid4, raid5, raid6, raid10. + +.B lvcreate \-\-type +.I RaidLevel +[\fIOPTIONS\fP] +.B \-\-name +.I Name +.B \-\-size +.I Size +.I VG +[\fIPVs\fP] + +To display the LV type of an existing LV, run: + +.B lvs -o name,segtype +\fIVG\fP/\fILV\fP + +(The LV type is also referred to as "segment type" or "segtype".) + +LVs can be created with the following types: + +.SS raid0 + +\& + +Also called striping, raid0 spreads LV data across multiple devices in +units of stripe size. This is used to increase performance. LV data will +be lost if any of the devices fail. + +.B lvcreate \-\-type raid0 +[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] +\fIVG\fP +[\fIPVs\fP] + +.HP +.B \-\-stripes +specifies the number of devices to spread the LV across. + +.HP +.B \-\-stripesize +specifies the size of each stripe in kilobytes. This is the amount of +data that is written to one device before moving to the next. +.P + +\fIPVs\fP specifies the devices to use. If not specified, lvm will choose +\fINumber\fP devices, one for each stripe. + +.SS raid1 + +\& + +Also called mirroring, raid1 uses multiple devices to duplicate LV data. +The LV data remains available if all but one of the devices fail. +The minimum number of devices (i.e. sub LV pairs) required is 2. + +.B lvcreate \-\-type raid1 +[\fB\-\-mirrors\fP \fINumber\fP] +\fIVG\fP +[\fIPVs\fP] + +.HP +.B \-\-mirrors +specifies the number of mirror images in addition to the original LV +image, e.g. \-\-mirrors 1 means there are two images of the data, the +original and one mirror image. +.P + +\fIPVs\fP specifies the devices to use. If not specified, lvm will choose +\fINumber\fP devices, one for each image. + +.SS raid4 + +\& + +raid4 is a form of striping that uses an extra, first device dedicated to +storing parity blocks. The LV data remains available if one device fails. The +parity is used to recalculate data that is lost from a single device. The +minimum number of devices required is 3. + +.B lvcreate \-\-type raid4 +[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] +\fIVG\fP +[\fIPVs\fP] + +.HP +.B \-\-stripes +specifies the number of devices to use for LV data. This does not include +the extra device lvm adds for storing parity blocks. \fINumber\fP stripes +requires \fINumber\fP+1 devices. \fINumber\fP must be 2 or more. + +.HP +.B \-\-stripesize +specifies the size of each stripe in kilobytes. This is the amount of +data that is written to one device before moving to the next. +.P + +\fIPVs\fP specifies the devices to use. If not specified, lvm will choose +\fINumber\fP+1 separate devices. + +raid4 is called non-rotating parity because the parity blocks are always +stored on the same device. + +.SS raid5 + +\& + +raid5 is a form of striping that uses an extra device for storing parity +blocks. LV data and parity blocks are stored on each device, typically in +a rotating pattern for performance reasons. The LV data remains available +if one device fails. The parity is used to recalculate data that is lost +from a single device. The minimum number of devices required is 3. + +.B lvcreate \-\-type raid5 +[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] +\fIVG\fP +[\fIPVs\fP] + +.HP +.B \-\-stripes +specifies the number of devices to use for LV data. This does not include +the extra device lvm adds for storing parity blocks. \fINumber\fP stripes +requires \fINumber\fP+1 devices. \fINumber\fP must be 2 or more. + +.HP +.B \-\-stripesize +specifies the size of each stripe in kilobytes. This is the amount of +data that is written to one device before moving to the next. +.P + +\fIPVs\fP specifies the devices to use. If not specified, lvm will choose +\fINumber\fP+1 separate devices. + +raid5 is called rotating parity because the parity blocks are placed on +different devices in a round-robin sequence. There are variations of +raid5 with different algorithms for placing the parity blocks. The +default variant is raid5_ls (raid5 left symmetric, which is a rotating +parity 0 with data restart.) See \fBRAID5 variants\fP below. + +.SS raid6 + +\& + +raid6 is a form of striping like raid5, but uses two extra devices for +parity blocks. LV data and parity blocks are stored on each device, typically +in a rotating pattern for perfomramce reasons. The +LV data remains available if up to two devices fail. The parity is used +to recalculate data that is lost from one or two devices. The minimum +number of devices required is 5. + +.B lvcreate \-\-type raid6 +[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] +\fIVG\fP +[\fIPVs\fP] + +.HP +.B \-\-stripes +specifies the number of devices to use for LV data. This does not include +the extra two devices lvm adds for storing parity blocks. \fINumber\fP +stripes requires \fINumber\fP+2 devices. \fINumber\fP must be 3 or more. + +.HP +.B \-\-stripesize +specifies the size of each stripe in kilobytes. This is the amount of +data that is written to one device before moving to the next. +.P + +\fIPVs\fP specifies the devices to use. If not specified, lvm will choose +\fINumber\fP+2 separate devices. + +Like raid5, there are variations of raid6 with different algorithms for +placing the parity blocks. The default variant is raid6_zr (raid6 zero +restart, aka left symmetric, which is a rotating parity 0 with data +restart.) See \fBRAID6 variants\fP below. + +.SS raid10 + +\& + +raid10 is a combination of raid1 and raid0, striping data across mirrored +devices. LV data remains available if one or more devices remains in each +mirror set. The minimum number of devices required is 4. + +.B lvcreate \-\-type raid10 +.RS +[\fB\-\-mirrors\fP \fINumberMirrors\fP] +.br +[\fB\-\-stripes\fP \fINumberStripes\fP \fB\-\-stripesize\fP \fISize\fP] +.br +\fIVG\fP +[\fIPVs\fP] +.RE + +.HP +.B \-\-mirrors +specifies the number of mirror images within each stripe. e.g. +\-\-mirrors 1 means there are two images of the data, the original and one +mirror image. + +.HP +.B \-\-stripes +specifies the total number of devices to use in all raid1 images (not the +number of raid1 devices to spread the LV across, even though that is the +effective result). The number of devices in each raid1 mirror will be +NumberStripes/(NumberMirrors+1), e.g. mirrors 1 and stripes 4 will stripe +data across two raid1 mirrors, where each mirror is devices. + +.HP +.B \-\-stripesize +specifies the size of each stripe in kilobytes. This is the amount of +data that is written to one device before moving to the next. +.P + +\fIPVs\fP specifies the devices to use. If not specified, lvm will choose +the necessary devices. Devices are used to create mirrors in the +order listed, e.g. for mirrors 1, stripes 2, listing PV1 PV2 PV3 PV4 +results in mirrors PV1/PV2 and PV3/PV4. + +RAID10 is not mirroring on top of stripes, which would be RAID01, which is +less tolerant of device failures. + + +.SH Synchronization + +Synchronization makes all the devices in a RAID LV consistent with each +other. + +In a RAID1 LV, all mirror images should have the same data. When a new +mirror image is added, or a mirror image is missing data, then images need +to be synchronized. Data blocks are copied from an existing image to a +new or outdated image to make them match. + +In a RAID 4/5/6 LV, parity blocks and data blocks should match based on +the parity calculation. When the devices in a RAID LV change, the data +and parity blocks can become inconsistent and need to be synchronized. +Correct blocks are read, parity is calculated, and recalculated blocks are +written. + +The RAID implementation keeps track of which parts of a RAID LV are +synchronized. This uses a bitmap saved in the RAID metadata. The bitmap +can exclude large parts of the LV from synchronization to reduce the +amount of work. Without this, the entire LV would need to be synchronized +every time it was activated. When a RAID LV is first created and +activated the first synchronization is called initialization. + +Automatic synchronization happens when a RAID LV is activated, but it is +usually partial because the bitmaps reduce the areas that are checked. +A full sync may become necessary when devices in the RAID LV are changed. + +The synchronization status of a RAID LV is reported by the +following command, where "image synced" means sync is complete: + +.B lvs -a -o name,sync_percent + + +.SS Scrubbing + +Scrubbing is a full scan/synchronization of the RAID LV requested by a user. +Scrubbing can find problems that are missed by partial synchronization. + +Scrubbing assumes that RAID metadata and bitmaps may be inaccurate, so it +verifies all RAID metadata, LV data, and parity blocks. Scrubbing can +find inconsistencies caused by hardware errors or degradation. These +kinds of problems may be undetected by automatic synchronization which +excludes areas outside of the RAID write-intent bitmap. + +The command to scrub a RAID LV can operate in two different modes: + +.B lvchange \-\-syncaction +.BR check | repair +.IR VG / LV + +.HP +.B check +Check mode is read\-only and only detects inconsistent areas in the RAID +LV, it does not correct them. + +.HP +.B repair +Repair mode checks and writes corrected blocks to synchronize any +inconsistent areas. + +.P + +Scrubbing can consume a lot of bandwidth and slow down application I/O on +the RAID LV. To control the I/O rate used for scrubbing, use: + +.HP +.B \-\-maxrecoveryrate +.BR \fIRate [ b | B | s | S | k | K | m | M | g | G ] +.br +Sets the maximum recovery rate for a RAID LV. \fIRate\fP is specified as +an amount per second for each device in the array. If no suffix is given, +then KiB/sec/device is assumed. Setting the recovery rate to \fB0\fP +means it will be unbounded. + +.HP +.BR \-\-minrecoveryrate +.BR \fIRate [ b | B | s | S | k | K | m | M | g | G ] +.br +Sets the minimum recovery rate for a RAID LV. \fIRate\fP is specified as +an amount per second for each device in the array. If no suffix is given, +then KiB/sec/device is assumed. Setting the recovery rate to \fB0\fP +means it will be unbounded. + +.P + +To display the current scrubbing in progress on an LV, including +the syncaction mode and percent complete, run: + +.B lvs -a -o name,raid_sync_action,sync_percent + +After scrubbing is complete, to display the number of inconsistent blocks +found, run: + +.B lvs -o name,raid_mismatch_count + +Also, if mismatches were found, the lvs attr field will display the letter +"m" (mismatch) in the 9th position, e.g. + +.nf +# lvs -o name,vgname,segtype,attr vg/lvol0 + LV VG Type Attr + lvol0 vg raid1 Rwi-a-r-m- +.fi + + +.SS Scrubbing Limitations + +The \fBcheck\fP mode can only report the number of inconsistent blocks, it +cannot report which blocks are inconsistent. This makes it impossible to +know which device has errors, or if the errors affect file system data, +metadata or nothing at all. + +The \fBrepair\fP mode can make the RAID LV data consistent, but it does +not know which data is correct. The result may be consistent but +incorrect data. When two different blocks of data must be made +consistent, it chooses the block from the device that would be used during +RAID intialization. However, if the PV holding corrupt data is known, +lvchange \-\-rebuild can be used to reconstruct the data on the bad +device. + +Future developments might include: + +Allowing a user to choose the correct version of data during repair. + +Using a majority of devices to determine the correct version of data to +use in a three-way RAID1 or RAID6 LV. + +Using a checksumming device to pin-point when and where an error occurs, +allowing it to be rewritten. + + +.SH SubLVs + +An LV is often a combination of other hidden LVs called SubLVs. The +SubLVs either use physical devices, or are built from other SubLVs +themselves. SubLVs hold LV data blocks, RAID parity blocks, and RAID +metadata. SubLVs are generally hidden, so the lvs \-a option is required +display them: + +.B lvs -a -o name,segtype,devices + +SubLV names begin with the visible LV name, and have an automatic suffix +indicating its role: + +.IP \(bu 3 +SubLVs holding LV data or parity blocks have the suffix _rimage_#. +These SubLVs are sometimes referred to as DataLVs. + +.IP \(bu 3 +SubLVs holding RAID metadata have the suffix _rmeta_#. RAID metadata +includes superblock information, RAID type, bitmap, and device health +information. These SubLVs are sometimes referred to as MetaLVs. + +.P + +SubLVs are an internal implementation detail of LVM. The way they are +used, constructed and named may change. + +The following examples show the SubLV arrangement for each of the basic +RAID LV types, using the fewest number of devices allowed for each. + +.SS Examples + +.B raid0 +.br +Each rimage SubLV holds a portion of LV data. No parity is used. +No RAID metadata is used. + +.nf +lvcreate --type raid0 --stripes 2 --name lvr0 ... + +lvs -a -o name,segtype,devices + lvr0 raid0 lvr0_rimage_0(0),lvr0_rimage_1(0) + [lvr0_rimage_0] linear /dev/sda(...) + [lvr0_rimage_1] linear /dev/sdb(...) +.fi + +.B raid1 +.br +Each rimage SubLV holds a complete copy of LV data. No parity is used. +Each rmeta SubLV holds RAID metadata. + +.nf +lvcreate --type raid1 --mirrors 1 --name lvr1 ... + +lvs -a -o name,segtype,devices + lvr1 raid1 lvr1_rimage_0(0),lvr1_rimage_1(0) + [lvr1_rimage_0] linear /dev/sda(...) + [lvr1_rimage_1] linear /dev/sdb(...) + [lvr1_rmeta_0] linear /dev/sda(...) + [lvr1_rmeta_1] linear /dev/sdb(...) +.fi + +.B raid4 +.br +Two rimage SubLVs each hold a portion of LV data and one rimage SubLV +holds parity. Each rmeta SubLV holds RAID metadata. + +.nf +lvcreate --type raid4 --stripes 2 --name lvr4 ... + +lvs -a -o name,segtype,devices + lvr4 raid4 lvr4_rimage_0(0),\\ + lvr4_rimage_1(0),\\ + lvr4_rimage_2(0) + [lvr4_rimage_0] linear /dev/sda(...) + [lvr4_rimage_1] linear /dev/sdb(...) + [lvr4_rimage_2] linear /dev/sdc(...) + [lvr4_rmeta_0] linear /dev/sda(...) + [lvr4_rmeta_1] linear /dev/sdb(...) + [lvr4_rmeta_2] linear /dev/sdc(...) +.fi + +.B raid5 +.br +Three rimage SubLVs each hold a portion of LV data and parity. +Each rmeta SubLV holds RAID metadata. + +.nf +lvcreate --type raid5 --stripes 2 --name lvr5 ... + +lvs -a -o name,segtype,devices + lvr5 raid5 lvr5_rimage_0(0),\\ + lvr5_rimage_1(0),\\ + lvr5_rimage_2(0) + [lvr5_rimage_0] linear /dev/sda(...) + [lvr5_rimage_1] linear /dev/sdb(...) + [lvr5_rimage_2] linear /dev/sdc(...) + [lvr5_rmeta_0] linear /dev/sda(...) + [lvr5_rmeta_1] linear /dev/sdb(...) + [lvr5_rmeta_2] linear /dev/sdc(...) +.fi + +.B raid6 +.br +Six rimage SubLVs each hold a portion of LV data and parity. +Each rmeta SubLV holds RAID metadata. + +.nf +lvcreate --type raid6 --stripes 3 --name lvr6 + +lvs -a -o name,segtype,devices + lvr6 raid6 lvr6_rimage_0(0),\\ + lvr6_rimage_1(0),\\ + lvr6_rimage_2(0),\\ + lvr6_rimage_3(0),\\ + lvr6_rimage_4(0),\\ + lvr6_rimage_5(0) + [lvr6_rimage_0] linear /dev/sda(...) + [lvr6_rimage_1] linear /dev/sdb(...) + [lvr6_rimage_2] linear /dev/sdc(...) + [lvr6_rimage_3] linear /dev/sdd(...) + [lvr6_rimage_4] linear /dev/sde(...) + [lvr6_rimage_5] linear /dev/sdf(...) + [lvr6_rmeta_0] linear /dev/sda(...) + [lvr6_rmeta_1] linear /dev/sdb(...) + [lvr6_rmeta_2] linear /dev/sdc(...) + [lvr6_rmeta_3] linear /dev/sdd(...) + [lvr6_rmeta_4] linear /dev/sde(...) + [lvr6_rmeta_5] linear /dev/sdf(...) + +.B raid10 +.br +Four rimage SubLVs each hold a portion of LV data. No parity is used. +Each rmeta SubLV holds RAID metadata. + +.nf +lvcreate --type raid10 --stripes 2 --mirrors 1 --name lvr10 + +lvs -a -o name,segtype,devices + lvr10 raid10 lvr10_rimage_0(0),\\ + lvr10_rimage_1(0),\\ + lvr10_rimage_2(0),\\ + lvr10_rimage_3(0) + [lvr10_rimage_0] linear /dev/sda(...) + [lvr10_rimage_1] linear /dev/sdb(...) + [lvr10_rimage_2] linear /dev/sdc(...) + [lvr10_rimage_3] linear /dev/sdd(...) + [lvr10_rmeta_0] linear /dev/sda(...) + [lvr10_rmeta_1] linear /dev/sdb(...) + [lvr10_rmeta_2] linear /dev/sdc(...) + [lvr10_rmeta_3] linear /dev/sdd(...) +.fi + + +.SH Device Failure + +Physical devices in a RAID LV can fail or be lost for multiple reasons. +A device could be disconnected, permanently failed, or temporarily +disconnected. The purpose of RAID LVs (levels 1 and higher) is to +continue operating in a degraded mode, without losing LV data, even after +a device fails. The number of devices that can fail without the loss of +LV data depends on the RAID level: + +.IP \[bu] 3 +RAID0 (striped) LVs cannot tolerate losing any devices. LV data will be +lost if any devices fail. + +.IP \[bu] 3 +RAID1 LVs can tolerate losing all but one device without LV data loss. + +.IP \[bu] 3 +RAID4 and RAID5 LVs can tolerate losing one device without LV data loss. + +.IP \[bu] 3 +RAID6 LVs can tolerate losing two devices without LV data loss. + +.IP \[bu] 3 +RAID10 is variable, and depends on which devices are lost. It can +tolerate losing all but one device in a single raid1 mirror without +LV data loss. + +.P + +If a RAID LV is missing devices, or has other device-related problems, lvs +reports this in the health_status (and attr) fields: + +.B lvs -o name,lv_health_status + +.B partial +.br +Devices are missing from the LV. This is also indicated by the letter "p" +(partial) in the 9th position of the lvs attr field. + +.B refresh needed +.br +A device was temporarily missing but has returned. The LV needs to be +refreshed to use the device again (which will usually require +partial synchronization). This is also indicated by the letter "r" (refresh +needed) in the 9th position of the lvs attr field. See +\fBRefreshing an LV\fP. This could also indicate a problem with the +device, in which case it should be be replaced, see +\fBReplacing Devices\fP. + +.B mismatches exist +.br +See +.BR Scrubbing . + +Most commands will also print a warning if a device is missing, e.g. +.br +.nf +WARNING: Device for PV uItL3Z-wBME-DQy0-... not found or rejected ... +.fi + +This warning will go away if the device returns or is removed from the +VG (see \fBvgreduce \-\-removemissing\fP). + + +.SS Activating an LV with missing devices + +A RAID LV that is missing devices may be activated or not, depending on +the "activation mode" used in lvchange: + +.B lvchange \-ay \-\-activationmode +.RB { complete | degraded | partial } +.IR VG / LV + +.B complete +.br +The LV is only activated if all devices are present. + +.B degraded +.br +The LV is activated with missing devices if the RAID level can +tolerate the number of missing devices without LV data loss. + +.B partial +.br +The LV is always activated, even if portions of the LV data are missing +because of the missing device(s). This should only be used to perform +recovery or repair operations. + +.BR lvm.conf (5) +.B activation/activation_mode +.br +controls the activation mode when not specified by the command. + +The default value is printed by: +.nf +lvmconfig --type default activation/activation_mode +.fi + +.SS Replacing Devices + +Devices in a RAID LV can be replaced with other devices in the VG. When +replacing devices that are no longer visible on the system, use lvconvert +\-\-repair. When replacing devices that are still visible, use lvconvert +\-\-replace. The repair command will attempt to restore the same number +of data LVs that were previously in the LV. The replace option can be +repeated to replace multiple PVs. Replacement devices can be optionally +listed with either option. + +.B lvconvert \-\-repair +.IR VG / LV +[\fINewPVs\fP] + +.B lvconvert \-\-replace +\fIOldPV\fP +.IR VG / LV +[\fINewPV\fP] + +.B lvconvert +.B \-\-replace +\fIOldPV1\fP +.B \-\-replace +\fIOldPV2\fP +... +.IR VG / LV +[\fINewPVs\fP] + +New devices require synchronization with existing devices, see +.BR Synchronization . + +.SS Refreshing an LV + +Refreshing a RAID LV clears any transient device failures (device was +temporarily disconnected) and returns the LV to its fully redundant mode. +Restoring a device will usually require at least partial synchronization +(see \fBSynchronization\fP). Failure to clear a transient failure results +in the RAID LV operating in degraded mode until it is reactivated. Use +the lvchange command to refresh an LV: + +.B lvchange \-\-refresh +.IR VG / LV + +.nf +# lvs -o name,vgname,segtype,attr,size vg + LV VG Type Attr LSize + raid1 vg raid1 Rwi-a-r-r- 100.00g + +# lvchange --refresh vg/raid1 + +# lvs -o name,vgname,segtype,attr,size vg + LV VG Type Attr LSize + raid1 vg raid1 Rwi-a-r--- 100.00g +.fi + +.SS Automatic repair + +If a device in a RAID LV fails, device-mapper in the kernel notifies the +.BR dmeventd (8) +monitoring process (see \fBMonitoring\fP). +dmeventd can be configured to automatically respond using: + +.BR lvm.conf (5) +.B activation/raid_fault_policy + +Possible settings are: + +.B warn +.br +A warning is added to the system log indicating that a device has +failed in the RAID LV. It is left to the user to repair the LV, e.g. +replace failed devices. + +.B allocate +.br +dmeventd automatically attempts to repair the LV using spare devices +in the VG. Note that even a transient failure is handled as a permanent +failure; a new device is allocated and full synchronization is started. + +The specific command run by dmeventd to warn or repair is: +.br +.B lvconvert \-\-repair \-\-use\-policies +.IR VG / LV + + +.SS Corrupted Data + +Data on a device can be corrupted due to hardware errors, without the +device ever being disconnected, and without any fault in the software. +This should be rare, and can be detected (see \fBScrubbing\fP). + + +.SS Rebuild specific PVs + +If specific PVs in a RAID LV are known to have corrupt data, the data on +those PVs can be reconstructed with: + +.B lvchange \-\-rebuild PV +.IR VG / LV + +The rebuild option can be repeated with different PVs to replace the data +on multiple PVs. + + +.SH Monitoring + +When a RAID LV is activated the \fBdmeventd\fP(8) process is started to +monitor the health of the LV. Various events detected in the kernel can +cause a notification to be sent from device-mapper to the monitoring +process, including device failures and synchronization completion (e.g. +for initialization or scrubbing). + +The LVM configuration file contains options that affect how the monitoring +process will respond to failure events (e.g. raid_fault_policy). It is +possible to turn on and off monitoring with lvchange, but it is not +recommended to turn this off unless you have a thorough knowledge of the +consequences. + + +.SH Configuration Options + +There are a number of options in the LVM configuration file that affect +the behavior of RAID LVs. The tunable options are listed +below. A detailed description of each can be found in the LVM +configuration file itself. +.br + mirror_segtype_default +.br + raid10_segtype_default +.br + raid_region_size +.br + raid_fault_policy +.br + activation_mode + + +.SH RAID1 Tuning + +A RAID1 LV can be tuned so that certain devices are avoided for reading +while all devices are still written to. + +.B lvchange +.BR \-\- [ raid ] writemostly +.BR \fIPhysicalVolume [ : { y | n | t }] +.IR VG / LV + +The specified device will be marked as "write mostly", which means that +reading from this device will be avoided, and other devices will be +preferred for reading (unless no other devices are available.) This +minimizes the I/O to the specified device. + +If the PV name has no suffix, the write mostly attribute is set. If the +PV name has the suffix \fB:n\fP, the write mostly attribute is cleared, +and the suffix \fB:t\fP toggles the current setting. + +The write mostly option can be repeated on the command line to change +multiple devices at once. + +To report the current write mostly setting, the lvs attr field will show +the letter "w" in the 9th position when write mostly is set: + +.B lvs -a -o name,attr + +When a device is marked write mostly, the maximum number of outstanding +writes to that device can be configured. Once the maximum is reached, +further writes become synchronous. When synchronous, a write to the LV +will not complete until writes to all the mirror images are complete. + +.B lvchange +.BR \-\- [ raid ] writebehind +.IR IOCount +.IR VG / LV + +To report the current write behind setting, run: + +.B lvs -o name,raid_write_behind + +When write behind is not configured, or set to 0, all LV writes are +synchronous. + + +.SH RAID Takeover + +RAID takeover is converting a RAID LV from one RAID level to another, e.g. +raid5 to raid6. Changing the RAID level is usually done to increase or +decrease resilience to device failures. This is done using lvconvert and +specifying the new RAID level as the LV type: + +.B lvconvert --type +.I RaidLevel +\fIVG\fP/\fILV\fP +[\fIPVs\fP] + +The most common and recommended RAID takeover conversions are: + +.HP +\fBlinear\fP to \fBraid1\fP +.br +Linear is a single image of LV data, and +converting it to raid1 adds a mirror image which is a direct copy of the +original linear image. + +.HP +\fBstriped\fP/\fBraid0\fP to \fBraid4/5/6\fP +.br +Adding parity devices to a +striped volume results in raid4/5/6. + +.P + +Unnatural conversions that are not recommended include converting between +striped and non-striped types. This is because file systems often +optimize I/O patterns based on device striping values. If those values +change, it can decrease performance. + +Converting to a higher RAID level requires allocating new SubLVs to hold +RAID metadata, and new SubLVs to hold parity blocks for LV data. +Converting to a lower RAID level removes the SubLVs that are no longer +needed. + +Conversion often requires full synchronization of the RAID LV (see +\fBSynchronization\fP). Converting to RAID1 requires copying all LV data +blocks to a new image on a new device. Converting to a parity RAID level +requires reading all LV data blocks, calculating parity, and writing the +new parity blocks. Synchronization can take a long time and degrade +performance (rate controls also apply to conversion, see +\fB\-\-maxrecoveryrate\fP.) + +Warning: though it is possible to create \fBstriped\fP LVs with up to 128 stripes, +a maximum of 64 stripes can be converted to \fBraid0\fP, 63 to \fBraid4/5\fP and +62 to \fBraid6\fP because of the added parity SubLVs. +A \fBstriped\fP LV with a maximum of 32 stripes can be converted to \fBraid10\fP. + +.P + +The following takeover conversions are currently possible: +.br +.IP \(bu 3 +between striped and raid0. +.IP \(bu 3 +between linear and raid1. +.IP \(bu 3 +between mirror and raid1. +.IP \(bu 3 +between 2-legged raid1 and raid4/5. +.IP \(bu 3 +between striped/raid0 and raid4. +.IP \(bu 3 +between striped/raid0 and raid5. +.IP \(bu 3 +between striped/raid0 and raid6. +.IP \(bu 3 +between raid4 and raid5. +.IP \(bu 3 +between raid4/raid5 and raid6. +.IP \(bu 3 +between striped/raid0 and raid10. + +.SS Examples + +1. Converting an LV from \fBlinear\fP to \fBraid1\fP. + +.nf +# lvs -a -o name,segtype,size vg + LV Type LSize + lv linear 300.00g + +# lvconvert --type raid1 --mirrors 1 vg/lv + +# lvs -a -o name,segtype,size vg + LV Type LSize + lv raid1 300.00g + [lv_rimage_0] linear 300.00g + [lv_rimage_1] linear 300.00g + [lv_rmeta_0] linear 3.00m + [lv_rmeta_1] linear 3.00m +.fi + +2. Converting an LV from \fBmirror\fP to \fBraid1\fP. + +.nf +# lvs -a -o name,segtype,size vg + LV Type LSize + lv mirror 100.00g + [lv_mimage_0] linear 100.00g + [lv_mimage_1] linear 100.00g + [lv_mlog] linear 3.00m +.IP \(bu 3 +between striped and raid4. + +.SS Examples + +1. Converting an LV from \fBlinear\fP to \fBraid1\fP. + +.nf +# lvs -a -o name,segtype,size vg + LV Type LSize + lv linear 300.00g + +# lvconvert --type raid1 --mirrors 1 vg/lv + +# lvs -a -o name,segtype,size vg + LV Type LSize + lv raid1 300.00g + [lv_rimage_0] linear 300.00g + [lv_rimage_1] linear 300.00g + [lv_rmeta_0] linear 3.00m + [lv_rmeta_1] linear 3.00m +.fi + +2. Converting an LV from \fBmirror\fP to \fBraid1\fP. + +.nf +# lvs -a -o name,segtype,size vg + LV Type LSize + lv mirror 100.00g + [lv_mimage_0] linear 100.00g + [lv_mimage_1] linear 100.00g + [lv_mlog] linear 3.00m + +# lvconvert --type raid1 vg/lv + +# lvs -a -o name,segtype,size vg + LV Type LSize + lv raid1 100.00g + [lv_rimage_0] linear 100.00g + [lv_rimage_1] linear 100.00g + [lv_rmeta_0] linear 3.00m + [lv_rmeta_1] linear 3.00m +.fi + +3. Converting an LV from \fBlinear\fP to \fBraid1\fP (with 3 images). + +.nf +Start with a linear LV: + +# lvcreate -L1G -n lv vg + +Convert the linear LV to raid1 with three images +(original linear image plus 2 mirror images): + +# lvconvert --type raid1 --mirrors 2 vg/lv +.fi + +4. Converting an LV from \fBstriped\fP (with 4 stripes) to \fBraid6_nc\fP. + +.nf +Start with a striped LV: + +# lvcreate --stripes 4 -L64M -n lv vg + +Convert the striped LV to raid6_n_6: + +# lvconvert --type raid6 vg/lv + +# lvs -a -o lv_name,segtype,sync_percent,data_copies + LV Type Cpy%Sync #Cpy + lv raid6_n_6 100.00 3 + [lv_rimage_0] linear + [lv_rimage_1] linear + [lv_rimage_2] linear + [lv_rimage_3] linear + [lv_rimage_4] linear + [lv_rimage_5] linear + [lv_rmeta_0] linear + [lv_rmeta_1] linear + [lv_rmeta_2] linear + [lv_rmeta_3] linear + [lv_rmeta_4] linear + [lv_rmeta_5] linear +.fi + +This convert begins by allocating MetaLVs (rmeta_#) for each of the +existing stripe devices. It then creates 2 additional MetaLV/DataLV pairs +(rmeta_#/rimage_#) for dedicated raid6 parity. + +If rotating data/parity is required, such as with raid6_nr, it must be +done by reshaping (see below). + + +.SH RAID Reshaping + +RAID reshaping is changing attributes of a RAID LV while keeping the same +RAID level. This includes changing RAID layout, stripe size, or number of +stripes. + +When changing the RAID layout or stripe size, no new SubLVs (MetaLVs or +DataLVs) need to be allocated, but DataLVs are extended by a small amount +(typically 1 extent). The extra space allows blocks in a stripe to be +updated safely, and not corrupted in case of a crash. If a crash occurs, +reshaping can just be restarted. + +(If blocks in a stripe were updated in place, a crash could leave them +partially updated and corrupted. Instead, an existing stripe is quiesced, +read, changed in layout, and the new stripe written to free space. Once +that is done, the new stripe is unquiesced and used.) + +.SS Examples + +1. Converting raid6_n_6 to raid6_nr with rotating data/parity. + +This conversion naturally follows a previous conversion from striped/raid0 +to raid6_n_6 (shown above). It completes the transition to a more +traditional RAID6. + +.nf +# lvs -o lv_name,segtype,sync_percent,data_copies + LV Type Cpy%Sync #Cpy + lv raid6_n_6 100.00 3 + [lv_rimage_0] linear + [lv_rimage_1] linear + [lv_rimage_2] linear + [lv_rimage_3] linear + [lv_rimage_4] linear + [lv_rimage_5] linear + [lv_rmeta_0] linear + [lv_rmeta_1] linear + [lv_rmeta_2] linear + [lv_rmeta_3] linear + [lv_rmeta_4] linear + [lv_rmeta_5] linear + +# lvconvert --type raid6_nr vg/lv + +# lvs -a -o lv_name,segtype,sync_percent,data_copies + LV Type Cpy%Sync #Cpy + lv raid6_nr 100.00 3 + [lv_rimage_0] linear + [lv_rimage_0] linear + [lv_rimage_1] linear + [lv_rimage_1] linear + [lv_rimage_2] linear + [lv_rimage_2] linear + [lv_rimage_3] linear + [lv_rimage_3] linear + [lv_rimage_4] linear + [lv_rimage_5] linear + [lv_rmeta_0] linear + [lv_rmeta_1] linear + [lv_rmeta_2] linear + [lv_rmeta_3] linear + [lv_rmeta_4] linear + [lv_rmeta_5] linear +.fi + +The DataLVs are larger (additional segment in each) which provides space +for out-of-place reshaping. The result is: + +.nf +# lvs -a -o lv_name,segtype,seg_pe_ranges,dataoffset + LV Type PE Ranges DOff + lv raid6_nr lv_rimage_0:0-32 \\ + lv_rimage_1:0-32 \\ + lv_rimage_2:0-32 \\ + lv_rimage_3:0-32 + [lv_rimage_0] linear /dev/sda:0-31 2048 + [lv_rimage_0] linear /dev/sda:33-33 + [lv_rimage_1] linear /dev/sdaa:0-31 2048 + [lv_rimage_1] linear /dev/sdaa:33-33 + [lv_rimage_2] linear /dev/sdab:1-33 2048 + [lv_rimage_3] linear /dev/sdac:1-33 2048 + [lv_rmeta_0] linear /dev/sda:32-32 + [lv_rmeta_1] linear /dev/sdaa:32-32 + [lv_rmeta_2] linear /dev/sdab:0-0 + [lv_rmeta_3] linear /dev/sdac:0-0 +.fi + +All segments with PE ranges '33-33' provide the out-of-place reshape space. +The dataoffset column shows that the data was moved from initial offset 0 to +2048 sectors on each component DataLV. + +For performance reasons the raid6_nr RaidLV can be restriped. +Convert it from 3-way striped to 5-way-striped. + +.nf +# lvconvert --stripes 5 -y tb/lv + Using default stripesize 64.00 KiB. + WARNING: Adding stripes to active logical volume tb/lv will grow it from 99 to 165 extents! + Run "lvresize -l99 tb/lv" to shrink it or use the additional capacity. + Logical volume tb/lv successfully converted. + +# lvs + LV VG Attr LSize Pool Origin Data% Meta% Move Log Cpy%Sync Convert + root fedora -wi-ao---- 15.00g + swap fedora -wi-ao---- 3.99g + lv tb rwi-a-r-s- 652.00m 52.94 + +# lvs -a -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb + LV Attr Type PE Ranges DOff + lv rwi-a-r--- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 lv_rimage_6:0-33 0 + [lv_rimage_0] iwi-aor--- linear /dev/sda:0-32 0 + [lv_rimage_0] iwi-aor--- linear /dev/sda:34-34 + [lv_rimage_1] iwi-aor--- linear /dev/sdaa:0-32 0 + [lv_rimage_1] iwi-aor--- linear /dev/sdaa:34-34 + [lv_rimage_2] iwi-aor--- linear /dev/sdab:0-32 0 + [lv_rimage_2] iwi-aor--- linear /dev/sdab:34-34 + [lv_rimage_3] iwi-aor--- linear /dev/sdac:1-34 0 + [lv_rimage_4] iwi-aor--- linear /dev/sdad:1-34 0 + [lv_rimage_5] iwi-aor--- linear /dev/sdae:1-34 0 + [lv_rimage_6] iwi-aor--- linear /dev/sdaf:1-34 0 + [lv_rmeta_0] ewi-aor--- linear /dev/sda:33-33 + [lv_rmeta_1] ewi-aor--- linear /dev/sdaa:33-33 + [lv_rmeta_2] ewi-aor--- linear /dev/sdab:33-33 + [lv_rmeta_3] ewi-aor--- linear /dev/sdac:0-0 + [lv_rmeta_4] ewi-aor--- linear /dev/sdad:0-0 + [lv_rmeta_5] ewi-aor--- linear /dev/sdae:0-0 + [lv_rmeta_6] ewi-aor--- linear /dev/sdaf:0-0 +.fi + +Stripes also can be removed from raid5 and 6. +Convert the 5-way striped raid6_nr LV to 4-way-striped. +The force option needs to be used, because removing stripes +(i.e. image SubLVs) from a RaidLV will shrink its size. + +.nf +# lvconvert --stripes 4 --force -y tb/lv + Using default stripesize 64.00 KiB. + WARNING: Removing stripes from active logical volume tb/lv will shrink it from 660.00 MiB to 528.00 MiB! + THIS MAY DESTROY (PARTS OF) YOUR DATA! + If that leaves the logical volume larger than 206 extents due to stripe rounding, + you may want to grow the content afterwards (filesystem etc.) + WARNING: too remove freed stripes after the conversion has finished, you have to run "lvconvert --stripes 4 tb/lv" + Logical volume tb/lv successfully converted. + +# lvs -a -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb + LV Attr Type PE Ranges DOff + lv rwi-a-r-s- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 lv_rimage_6:0-33 0 + [lv_rimage_0] Iwi-aor--- linear /dev/sda:0-32 0 + [lv_rimage_0] Iwi-aor--- linear /dev/sda:34-34 + [lv_rimage_1] Iwi-aor--- linear /dev/sdaa:0-32 0 + [lv_rimage_1] Iwi-aor--- linear /dev/sdaa:34-34 + [lv_rimage_2] Iwi-aor--- linear /dev/sdab:0-32 0 + [lv_rimage_2] Iwi-aor--- linear /dev/sdab:34-34 + [lv_rimage_3] Iwi-aor--- linear /dev/sdac:1-34 0 + [lv_rimage_4] Iwi-aor--- linear /dev/sdad:1-34 0 + [lv_rimage_5] Iwi-aor--- linear /dev/sdae:1-34 0 + [lv_rimage_6] Iwi-aor-R- linear /dev/sdaf:1-34 0 + [lv_rmeta_0] ewi-aor--- linear /dev/sda:33-33 + [lv_rmeta_1] ewi-aor--- linear /dev/sdaa:33-33 + [lv_rmeta_2] ewi-aor--- linear /dev/sdab:33-33 + [lv_rmeta_3] ewi-aor--- linear /dev/sdac:0-0 + [lv_rmeta_4] ewi-aor--- linear /dev/sdad:0-0 + [lv_rmeta_5] ewi-aor--- linear /dev/sdae:0-0 + [lv_rmeta_6] ewi-aor-R- linear /dev/sdaf:0-0 +.fi + +The 's' in column 9 of the attribute field shows the RaidLV is still reshaping. +The 'R' in the same column of the attribute field shows the freed image Sub LVs which will need removing once the reshaping finished. + +.nf +# lvs -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb + LV Attr Type PE Ranges DOff + lv rwi-a-r-R- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 lv_rimage_6:0-33 8192 +.fi + +Now that the reshape is finished the 'R' atribute on the RaidLV shows images can be removed. + +.nf +# lvs -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb + LV Attr Type PE Ranges DOff + lv rwi-a-r-R- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 lv_rimage_6:0-33 8192 +.fi + +This is achieved by repeating the command ("lvconvert --stripes 4 tb/lv" would be sufficient). + +.nf +# lvconvert --stripes 4 --force -y tb/lv + Using default stripesize 64.00 KiB. + Logical volume tb/lv successfully converted. + +# lvs -a -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb + LV Attr Type PE Ranges DOff + lv rwi-a-r--- raid6_nr lv_rimage_0:0-33 lv_rimage_1:0-33 lv_rimage_2:0-33 ... lv_rimage_5:0-33 8192 + [lv_rimage_0] iwi-aor--- linear /dev/sda:0-32 8192 + [lv_rimage_0] iwi-aor--- linear /dev/sda:34-34 + [lv_rimage_1] iwi-aor--- linear /dev/sdaa:0-32 8192 + [lv_rimage_1] iwi-aor--- linear /dev/sdaa:34-34 + [lv_rimage_2] iwi-aor--- linear /dev/sdab:0-32 8192 + [lv_rimage_2] iwi-aor--- linear /dev/sdab:34-34 + [lv_rimage_3] iwi-aor--- linear /dev/sdac:1-34 8192 + [lv_rimage_4] iwi-aor--- linear /dev/sdad:1-34 8192 + [lv_rimage_5] iwi-aor--- linear /dev/sdae:1-34 8192 + [lv_rmeta_0] ewi-aor--- linear /dev/sda:33-33 + [lv_rmeta_1] ewi-aor--- linear /dev/sdaa:33-33 + [lv_rmeta_2] ewi-aor--- linear /dev/sdab:33-33 + [lv_rmeta_3] ewi-aor--- linear /dev/sdac:0-0 + [lv_rmeta_4] ewi-aor--- linear /dev/sdad:0-0 + [lv_rmeta_5] ewi-aor--- linear /dev/sdae:0-0 + +# lvs -a -o lv_name,attr,segtype,reshapelen tb + LV Attr Type RSize + lv rwi-a-r--- raid6_nr 24.00m + [lv_rimage_0] iwi-aor--- linear 4.00m + [lv_rimage_0] iwi-aor--- linear + [lv_rimage_1] iwi-aor--- linear 4.00m + [lv_rimage_1] iwi-aor--- linear + [lv_rimage_2] iwi-aor--- linear 4.00m + [lv_rimage_2] iwi-aor--- linear + [lv_rimage_3] iwi-aor--- linear 4.00m + [lv_rimage_4] iwi-aor--- linear 4.00m + [lv_rimage_5] iwi-aor--- linear 4.00m + [lv_rmeta_0] ewi-aor--- linear + [lv_rmeta_1] ewi-aor--- linear + [lv_rmeta_2] ewi-aor--- linear + [lv_rmeta_3] ewi-aor--- linear + [lv_rmeta_4] ewi-aor--- linear + [lv_rmeta_5] ewi-aor--- linear +.fi + +If the reshape space shall be removed any lvconvert command not changing the layout can be used: + +.nf +# lvconvert --stripes 4 tb/lv + Using default stripesize 64.00 KiB. + No change in RAID LV tb/lv layout, freeing reshape space. + Logical volume tb/lv successfully converted. + +# lvs -a -o lv_name,attr,segtype,reshapelen tb + LV Attr Type RSize + lv rwi-a-r--- raid6_nr 0 + [lv_rimage_0] iwi-aor--- linear 0 + [lv_rimage_0] iwi-aor--- linear + [lv_rimage_1] iwi-aor--- linear 0 + [lv_rimage_1] iwi-aor--- linear + [lv_rimage_2] iwi-aor--- linear 0 + [lv_rimage_2] iwi-aor--- linear + [lv_rimage_3] iwi-aor--- linear 0 + [lv_rimage_4] iwi-aor--- linear 0 + [lv_rimage_5] iwi-aor--- linear 0 + [lv_rmeta_0] ewi-aor--- linear + [lv_rmeta_1] ewi-aor--- linear + [lv_rmeta_2] ewi-aor--- linear + [lv_rmeta_3] ewi-aor--- linear + [lv_rmeta_4] ewi-aor--- linear + [lv_rmeta_5] ewi-aor--- linear +.fi + +In case the RaidLV should be converted to striped: + +.nf +# lvconvert --type striped tb/lv + Unable to convert LV tb/lv from raid6_nr to striped. + Converting tb/lv from raid6_nr is directly possible to the following layouts: + raid6_nc + raid6_zr + raid6_la_6 + raid6_ls_6 + raid6_ra_6 + raid6_rs_6 + raid6_n_6 + +# lvconvert --type raid6_n_6 + Using default stripesize 64.00 KiB. + Converting raid6_nr LV tb/lv to raid6_n_6. +Are you sure you want to convert raid6_nr LV tb/lv? [y/n]: y + Logical volume tb/lv successfully converted. + +# lvconvert -y --type striped tb/lv + Logical volume tb/lv successfully converted. + +[root at vm46 ~]# lvs -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb + LV Attr Type PE Ranges DOff + lv -wi-a----- striped /dev/sda:2-32 /dev/sdaa:2-32 /dev/sdab:2-32 /dev/sdac:3-33 + lv -wi-a----- striped /dev/sda:34-35 /dev/sdaa:34-35 /dev/sdab:34-35 /dev/sdac:34-35 +.fi + +From striped we can convert to raid10 + +.nf +# lvconvert -y --type raid10 tb/lv + Using default stripesize 64.00 KiB. + Logical volume tb/lv successfully converted. + +# lvs -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb + LV Attr Type PE Ranges DOff + lv rwi-a-r--- raid10 lv_rimage_0:0-32 lv_rimage_4:0-32 lv_rimage_1:0-32 ... lv_rimage_3:0-32 lv_rimage_7:0-32 0 + +# lvs -a -o lv_name,attr,segtype,seg_pe_ranges,dataoffset tb + WARNING: Cannot find matching striped segment for tb/lv_rimage_3. + LV Attr Type PE Ranges DOff + lv rwi-a-r--- raid10 lv_rimage_0:0-32 lv_rimage_4:0-32 lv_rimage_1:0-32 ... lv_rimage_3:0-32 lv_rimage_7:0-32 0 + [lv_rimage_0] iwi-aor--- linear /dev/sda:2-32 0 + [lv_rimage_0] iwi-aor--- linear /dev/sda:34-35 + [lv_rimage_1] iwi-aor--- linear /dev/sdaa:2-32 0 + [lv_rimage_1] iwi-aor--- linear /dev/sdaa:34-35 + [lv_rimage_2] iwi-aor--- linear /dev/sdab:2-32 0 + [lv_rimage_2] iwi-aor--- linear /dev/sdab:34-35 + [lv_rimage_3] iwi-XXr--- linear /dev/sdac:3-35 0 + [lv_rimage_4] iwi-aor--- linear /dev/sdad:1-33 0 + [lv_rimage_5] iwi-aor--- linear /dev/sdae:1-33 0 + [lv_rimage_6] iwi-aor--- linear /dev/sdaf:1-33 0 + [lv_rimage_7] iwi-aor--- linear /dev/sdag:1-33 0 + [lv_rmeta_0] ewi-aor--- linear /dev/sda:0-0 + [lv_rmeta_1] ewi-aor--- linear /dev/sdaa:0-0 + [lv_rmeta_2] ewi-aor--- linear /dev/sdab:0-0 + [lv_rmeta_3] ewi-aor--- linear /dev/sdac:0-0 + [lv_rmeta_4] ewi-aor--- linear /dev/sdad:0-0 + [lv_rmeta_5] ewi-aor--- linear /dev/sdae:0-0 + [lv_rmeta_6] ewi-aor--- linear /dev/sdaf:0-0 + [lv_rmeta_7] ewi-aor--- linear /dev/sdag:0-0 +.fi + +raid10 allows to add stripes but can't remove them. + + +A more elaborate example to convert from linear to striped +with interim conversions to raid1 then raid5 followed +by restripe (4 steps). + +We start with the linear LV. + +.nf +# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg + LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices + lv -wi-a----- 128.00m linear 1 0 /dev/sda(0) +.fi + +Then convert it to a 2-way raid1. + +.nf +# lvconvert -m1 vg/lv + Logical volume vg/lv successfully converted. + +# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg + LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices + lv rwi-a-r--- 128.00m raid1 100.00 2 0 lv_rimage_0(0),lv_rimage_1(0) + [lv_rimage_0] iwi-aor--- 128.00m linear 1 0 /dev/sda(0) + [lv_rimage_1] iwi-aor--- 128.00m linear 1 0 /dev/sdhx(1) + [lv_rmeta_0] ewi-aor--- 4.00m linear 1 0 /dev/sda(32) + [lv_rmeta_1] ewi-aor--- 4.00m linear 1 0 /dev/sdhx(0) +.fi + +Once the raid1 LV is fully synchronized we convert it to raid5_n (only 2-way raid1 +LVs can be converted to raid5). We select raid5_n here because it has dedicated parity +SubLVs at the end and can be converted to striped directly without any additional +conversion. + +.nf +# lvconvert -y --ty raid5_n vg/lv + Using default stripesize 64.00 KiB. + Logical volume vg/lv successfully converted. + +# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg + LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices + lv rwi-a-r--- 128.00m raid5_n 100.00 1 64.00k 0 lv_rimage_0(0),lv_rimage_1(0) + [lv_rimage_0] iwi-aor--- 128.00m linear 1 0 0 /dev/sda(0) + [lv_rimage_1] iwi-aor--- 128.00m linear 1 0 0 /dev/sdhx(1) + [lv_rmeta_0] ewi-aor--- 4.00m linear 1 0 /dev/sda(32) + [lv_rmeta_1] ewi-aor--- 4.00m linear 1 0 /dev/sdhx(0) +.fi + +Now we'll change the number of data stripes from 1 to 5 and request 128K stripe size +in one command. This will grow the size of the LV by a factor of 5 (we add 4 data stripes +to the one given). That additonal space can be used by e.g. growing any contained filesystem +or the LV can be reduced in size after the reshaping conversion has finished. + +.nf +# lvconvert --yes --stripesize 128k --stripes 5 vg/lv + Converting stripesize 64.00 KiB of raid5_n LV vg/lv to 128.00 KiB. + WARNING: Adding stripes to active logical volume vg/lv will grow it from 32 to 160 extents! + Run "lvresize -l32 vg/lv" to shrink it or use the additional capacity. + Logical volume vg/lv successfully converted. + +# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg + LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices + lv rwi-a-r--- 640.00m raid5_n 100.00 5 128.00k 6 lv_rimage_0(0),lv_rimage_1(0),lv_rimage_2(0),lv_rimage_3(0),lv_rimage_4(0),lv_rimage_5(0) + [lv_rimage_0] iwi-aor--- 132.00m linear 1 0 1 /dev/sda(33) + [lv_rimage_0] iwi-aor--- 132.00m linear 1 0 /dev/sda(0) + [lv_rimage_1] iwi-aor--- 132.00m linear 1 0 1 /dev/sdhx(33) + [lv_rimage_1] iwi-aor--- 132.00m linear 1 0 /dev/sdhx(1) + [lv_rimage_2] iwi-aor--- 132.00m linear 1 0 1 /dev/sdhw(33) + [lv_rimage_2] iwi-aor--- 132.00m linear 1 0 /dev/sdhw(1) + [lv_rimage_3] iwi-aor--- 132.00m linear 1 0 1 /dev/sdhv(33) + [lv_rimage_3] iwi-aor--- 132.00m linear 1 0 /dev/sdhv(1) + [lv_rimage_4] iwi-aor--- 132.00m linear 1 0 1 /dev/sdhu(33) + [lv_rimage_4] iwi-aor--- 132.00m linear 1 0 /dev/sdhu(1) + [lv_rimage_5] iwi-aor--- 132.00m linear 1 0 1 /dev/sdht(33) + [lv_rimage_5] iwi-aor--- 132.00m linear 1 0 /dev/sdht(1) + [lv_rmeta_0] ewi-aor--- 4.00m linear 1 0 /dev/sda(32) + [lv_rmeta_1] ewi-aor--- 4.00m linear 1 0 /dev/sdhx(0) + [lv_rmeta_2] ewi-aor--- 4.00m linear 1 0 /dev/sdhw(0) + [lv_rmeta_3] ewi-aor--- 4.00m linear 1 0 /dev/sdhv(0) + [lv_rmeta_4] ewi-aor--- 4.00m linear 1 0 /dev/sdhu(0) + [lv_rmeta_5] ewi-aor--- 4.00m linear 1 0 /dev/sdht(0) +.fi + +Once the conversion has finished we can can convert to striped. + +.nf +[root at vm46 ~]# lvconvert -y --ty striped vg/lv + Logical volume vg/lv successfully converted. + +[root at vm46 ~]# lvs -aoname,attr,size,segtype,syncpercent,datastripes,stripesize,reshapelenle,devices vg|sed 's/ *$//' + LV Attr LSize Type Cpy%Sync #DStr Stripe RSize Devices + lv -wi-a----- 640.00m striped 5 128.00k /dev/sda(33),/dev/sdhx(33),/dev/sdhw(33),/dev/sdhv(33),/dev/sdhu(33) + lv -wi-a----- 640.00m striped 5 128.00k /dev/sda(0),/dev/sdhx(1),/dev/sdhw(1),/dev/sdhv(1),/dev/sdhu(1) +.fi + +Reversing these steps wil convert a given striped LV to linear. + +Mind the fact that stripes are removed thus the capacity of the RaidLV will shrink. + +"lvconvert --stripes 1 vg/lv" for converting to 1 stripe will inform upfront about +the reduced size to allow for resizing the content or growing the RaidLV before +actually converting to 1 stripe. The \fB\-\-force\fP option is needed to +allow stripe removing conversions to prevent data loss. + +Of course any interim step can be the intended last one (e.g. striped -> raid1). +.. + +.SH RAID5 Variants + +raid5_ls +.br +\[bu] +RAID5 left symmetric +.br +\[bu] +Rotating parity N with data restart + +raid5_la +.br +\[bu] +RAID5 left symmetric +.br +\[bu] +Rotating parity N with data continuation + +raid5_rs +.br +\[bu] +RAID5 right symmetric +.br +\[bu] +Rotating parity 0 with data restart + +raid5_ra +.br +\[bu] +RAID5 right asymmetric +.br +\[bu] +Rotating parity 0 with data continuation + +raid5_n +.br +\[bu] +RAID5 parity n +.br +\[bu] +Dedicated parity device n used for striped/raid0 conversions +\[bu] +Used for RAID Takeover + +.SH RAID6 Variants + +raid6 +.br +\[bu] +RAID6 zero restart (aka left symmetric) +.br +\[bu] +Rotating parity 0 with data restart +.br +\[bu] +Same as raid6_zr + +raid6_zr +.br +\[bu] +RAID6 zero restart (aka left symmetric) +.br +\[bu] +Rotating parity 0 with data restart + +raid6_nr +.br +\[bu] +RAID6 N restart (aka right symmetric) +.br +\[bu] +Rotating parity N with data restart + +raid6_nc +.br +\[bu] +RAID6 N continue +.br +\[bu] +Rotating parity N with data continuation + +raid6_n_6 +.br +\[bu] +RAID6 last parity devices +.br +\[bu] +Dedicated last parity devices used for striped/raid0 conversions +\[bu] +Used for RAID Takeover + +raid6_{ls,rs,la,ra}_6 +.br +\[bu] +RAID6 last parity device +.br +\[bu] +Dedicated last parity device used for conversions from/to raid5_{ls,rs,la,ra} + +raid6_n_6 +.br +\[bu] +RAID6 N continue +.br +\[bu] +Fixed P-Syndrome N-1 and Q-Syndrome N with striped data +.br +\[bu] +Used for RAID Takeover + +raid6_ls_6 +.br +\[bu] +RAID6 N continue +.br +\[bu] +Same as raid5_ls for N-1 disks with fixed Q-Syndrome N +.br +\[bu] +Used for RAID Takeover + +raid6_la_6 +.br +\[bu] +RAID6 N continue +.br +\[bu] +Same as raid5_la for N-1 disks with fixed Q-Syndrome N +.br +\[bu] +Used forRAID Takeover + +raid6_rs_6 +.br +\[bu] +RAID6 N continue +.br +\[bu] +Same as raid5_rs for N-1 disks with fixed Q-Syndrome N +.br +\[bu] +Used for RAID Takeover + +raid6_ra_6 +.br +\[bu] +RAID6 N continue +.br +\[bu] +Same as raid5_ra for N-1 disks with fixed Q-Syndrome N +.br +\[bu] +Used for RAID Takeover + + +.ig +.SH RAID Duplication + +RAID LV conversion (takeover or reshaping) can be done out\-of\-place by +copying the LV data onto new devices while changing the RAID properties. +Copying avoids modifying the original LV but requires additional devices. +Once the LV data has been copied/converted onto the new devices, there are +multiple options: + +1. The RAID LV can be switched over to run from just the new devices, and +the original copy of the data removed. The converted LV then has the new +RAID properties, and exists on new devices. The old devices holding the +original data can be removed or reused. + +2. The new copy of the data can be dropped, leaving the original RAID LV +unchanged and using its original devices. + +3. The new copy of the data can be separated and used as a new independent +LV, leaving the original RAID LV unchanged on its original devices. + +The command to start duplication is: + +.B lvconvert \-\-type +.I RaidLevel +[\fB\-\-stripes\fP \fINumber\fP \fB\-\-stripesize\fP \fISize\fP] +.RS +.B \-\-duplicate +.IR VG / LV +[\fIPVs\fP] +.RE + +.HP +.B \-\-duplicate +.br +Specifies that the LV conversion should be done out\-of\-place, copying +LV data to new devices while converting. + +.HP +.BR \-\-type , \-\-stripes , \-\-stripesize +.br +Specifies the RAID properties to use when creating the copy. + +.P +\fIPVs\fP specifies the new devices to use. + +The steps in the duplication process: + +.IP \(bu 3 +LVM creates a new LV on new devices using the specified RAID properties +(type, stripes, etc) and optionally specified devices. + +.IP \(bu 3 +LVM changes the visible RAID LV to type raid1, making the original LV the +first raid1 image (SubLV 0), and the new LV the second raid1 image +(SubLV 1). + +.IP \(bu 3 +The RAID1 synchronization process copies data from the original LV +image (SubLV 0) to the new LV image (SubLV 1). + +.IP \(bu 3 +When synchronization is complete, the original and new LVs are +mirror images of each other and can be separated. + +.P + +The duplication process retains both the original and new LVs (both +SubLVs) until an explicit unduplicate command is run to separate them. The +unduplicate command specifies if the original LV should use the old +devices (SubLV 0) or the new devices (SubLV 1). + +To make the RAID LV use the data on the old devices, and drop the copy on +the new devices, specify the name of SubLV 0 (suffix _dup_0): + +.B lvconvert \-\-unduplicate +.BI \-\-name +.IB LV _dup_0 +.IR VG / LV + +To make the RAID LV use the data copy on the new devices, and drop the old +devices, specify the name of SubLV 1 (suffix _dup_1): + +.B lvconvert \-\-unduplicate +.BI \-\-name +.IB LV _dup_1 +.IR VG / LV + +FIXME: To make the LV use the data on the original devices, but keep the +data copy as a new LV, ... + +FIXME: include how splitmirrors can be used. + + +.SH RAID1E + +TODO +.. + +.SH History + +The 2.6.38-rc1 version of the Linux kernel introduced a device-mapper +target to interface with the software RAID (MD) personalities. This +provided device-mapper with RAID 4/5/6 capabilities and a larger +development community. Later, support for RAID1, RAID10, and RAID1E (RAID +10 variants) were added. Support for these new kernel RAID targets was +added to LVM version 2.02.87. The capabilities of the LVM \fBraid1\fP +type have surpassed the old \fBmirror\fP type. raid1 is now recommended +instead of mirror. raid1 became the default for mirroring in LVM version +2.02.100. + diff --git a/man/lvmreport.7.in b/man/lvmreport.7.in deleted file mode 100644 index 7a26401..0000000 --- a/man/lvmreport.7.in +++ /dev/null @@ -1,1810 +0,0 @@ -.TH "LVMREPORT" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" - -.SH NAME -lvmreport \(em LVM reporting and related features - -.SH DESCRIPTION -LVM uses single reporting infrastructure that sets standard on LVM command's -output and it provides wide range of configuration settings and command line -options to customize report and filter the report's output. - -.SH Categorization based on reporting facility - -Based on functionality, commands which make use of the reporting infrastructure -are divided in two groups: -.IP \fBReport-oriented commands\fP -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 \fBmain report\fP. The set of report-only commands include: -pvs, vgs, lvs, pvdisplay, vgdisplay, lvdisplay, lvm devtypes, lvm fullreport. -For further information about main report, see \fBmain report specifics\fP. -.IP \fBProcessing-oriented commands\fP -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. - -.RE -If enabled, so called \fBlog report\fP 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 \fBlog report specifics\fP for more -information about this report type. - - -.SH Terms - -When describing reporting functionality and features in this text, we will -use terms \fBrow\fP and \fBcolumn\fP. 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 \fBcolumn headings\fP -which are short descriptions for the columns. The columns are referenced by -\fBcolumn names\fP. Please note that this text is also using term \fBfield\fP -interchangeably with the term \fBcolumn\fP. Most of the time the term columns -is abbreviated as \fBcol\fP in configuration. - -.SH Common report configuration settings and command line options - -There are common configuration settings and command line options which apply -to both \fBmain report\fP and \fBlog report\fP. Following lists contain all -of them, separated into groups based on their use. - -.RS -\fBCommon configuration settings:\fP - -.RS - -.IP \[bu] 3 -Changing report output format, composition and other output modifiers: -.RS -.IP - 3 -global/units -.IP - 3 -global/suffix -.IP - 3 -report/output_format -.IP - 3 -report/compact_output -.IP - 3 -report/compact_output_cols -.IP - 3 -report/aligned -.IP - 3 -report/headings -.IP - 3 -report/separator -.IP - 3 -report/list_item_separator -.IP - 3 -report/prefixes -.IP - 3 -report/quoted -.IP - 3 -report/columns_as_rows -.IP - 3 -report/binary_values_as_numeric -.IP - 3 -report/time_format -.IP - 3 -report/mark_hidden_devices -.IP - 3 -report/two_word_unknown_device -.RE - -.IP \[bu] 3 -Special settings -.RS -.IP - 3 -report/buffered -.RE - -.RE - -.RE - -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 \fBlvmconfig --type default --withcomments \fP. There are -more configuration settings in addition to the common set listed above, but -they are specific to either \fBmain report\fP or \fBlog report\fP, -see \fBmain report specifics\fP and \fBlog report specifics\fP 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. - -.RS -\fBCommon command line options:\fP - -.RS - -.IP \[bu] 3 -Definition of the set set of fields to use -.RS -.IP - 3 ---options|-o FieldSet -.br -Field set to use. See \fBmain report specifics\fP and -\fBlog report specifics\fP for information about field sets configured with -global configuratin settings that this option overrides. -.IP - 3 ---options|-o+ FieldSet -.br -Fields to include to current field set. See \fBmain report specifics\fP\ and -\fBlog report specifics\fP for information about field sets configured with -global configuration settings that this option extends. -.IP - 3 ---options|-o- FieldSet -.br -Fields to exclude from current field set. See \fBmain report specifics\fP and -\fBlog report specifics\fP for information about field sets configured with -global configuration settings that this option reduces. -.IP - 3 ---options|-o# FieldSet -.br -Compaction of unused fields. Overrides report/compact_output_cols configuration -setting. -.RE - -.IP \[bu] 3 -Sorting -.RS -.IP - 3 ---sort|-O+ FieldSet -.br -Fields to sort by in ascending order. See \fBmain report specifics\fP and -\fBlog report specifics\fP for information about field sets configured with -global configuration settings that this option overrides. -.IP - 3 ---sort|-O- FieldSet -.br -Fields to sort by in descending order. See \fBmain report specifics\fP and -\fBlog report specifics\fP for information about fields sets configured with -global configuration settings that this options overrides. -.RE - -.IP \[bu] 3 -Selection -.RS -.IP - 3 ---select|-S Selection -.br -Define selection criteria for report output. For \fBlog report\fP, this also -overrides log/command_log_selection configuration setting, see also -\fBlog report specifics\fP. -.RE - -.IP \[bu] 3 -Changing output format and composition -.RS -.IP - 3 ---reportformat -.br -Overrides report/output_format configuration setting. -.IP - 3 ---aligned -.br -Overrides report/aligned configuration setting. -.IP - 3 ---binary -.br -Overrides report/binary_values_as_numeric configuration setting. -.IP - 3 ---nameprefixes -.br -Overrides report/prefixes configuration setting. -.IP - 3 ---noheadings -.br -Overrides report/noheadings configuration setting. -.IP - 3 ---nosuffix -.br -Overrides global/suffix configuration setting. -.IP - 3 ---rows -.br -Overrides report/columns_as_rows configuration setting. -.IP - 3 ---separator -.br -Overrides report/separator configuration setting. -.IP - 3 ---units -.br -Overrides global/units configuration setting. -.IP - 3 ---unquoted -.br -Overrides report/quoted configuration setting. -.RE - -.IP \[bu] 3 -Special options -.RS -.IP - 3 ---configreport \fBReportName\fP -.br -This defines the \fBReportName\fP for which any subsequent -o|--columns, --O|--sort or -S|--select applies to. See also \fBmain report specifics\fP -and \fBlog report specifics\fP for possible \fBReportName\fP values. -.IP - 3 ---logonly -.br -When an LVM command contains both \fBmain report\fP and \fBlog report\fP, -this option suppresses the \fBmain report\fP output and it causes the -\fBlog report\fP output to be displayed only. -.IP - 3 ---unbuffered -.br -Overrides report/bufffered configuration setting. -.RE - -.RE - -.RE - -The \fBFieldSet\fP 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 \fBSelection\fP -is a string with \fBselection criteria\fP, see also \fBSelection\fP paragraph -below for more information about constructing these criteria. - - -.SH Main report specifics - -The \fBmain report\fP currently encompasses these distinct subtypes, referenced -by their name - \fBReportName\fP 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 \fBReportName\fP): - -.RS - -.IP \[bu] 3 -\fBpv\fP representing report about Physical Volumes (\fBpvs\fP) -.RS -.IP - 3 -report/pvs_cols -.IP - 3 -report/pvs_sort -.RE - -.IP \[bu] 3 -\fBpvseg\fP representing report about Physical Volume Segments (\fBpvs --segments\fP) -.RS -.IP - 3 -report/pvseg_cols -.IP - 3 -report/pvseg_sort -.RE - -.IP \[bu] 3 -\fBvg\fP representing report about Volume Groups (\fBvgs\fP) -.RS -.IP - 3 -report/vgs_cols -.IP - 3 -report/vgs_sort -.RE - -.IP \[bu] 3 -\fBlv\fP representing report about Logical Volumes (\fBlvs\fP) -.RS -.IP - 3 -report/lvs_cols -.IP - 3 -report/lvs_sort -.RE - -.IP \[bu] 3 -\fBseg\fP representing report about Logical Volume Segments (\fBlvs --segments\fP) -.RS -.IP - 3 -report/segs_cols -.IP - 3 -report/segs_sort -.RE - -.IP \[bu] 3 -\fBfull\fP representing report combining all of the above as a whole (\fBlvm fullreport\fP) -.RS -.IP - 3 -report/pvs_cols_full -.IP - 3 -report/pvs_sort_full -.IP - 3 -report/pvsegs_cols_full -.IP - 3 -report/pvseg_sort_full -.IP - 3 -report/vgs_cols_full -.IP - 3 -report/vgs_sort_full -.IP - 3 -report/lvs_cols_full -.IP - 3 -report/lvs_sort_full -.IP - 3 -report/segs_cols_full -.IP - 3 -report/segs_sort_full -.RE - -.IP \[bu] 3 -\fBdevtype\fP representing report about device types (\fBlvm devtypes\fP) -.RS -.IP - 3 -report/devtypes_cols -.IP - 3 -report/devtypes_sort -.RE - -.RE - -Use \fBpvs, vgs, lvs -o help\fP or \fBlvm devtypes -o help\fP 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 \fBfull\fP, it's not necessary to use -\fB--configreport ReportName\fP to denote which report any subsequent -\fB-o, -O or -S\fP option applies to as they always apply to the single main -report type. Currently, \fBlvm fullreport\fP is the only command that -includes more than one \fBmain report\fP subtype. Therefore, the --configreport -is particularly suitable for the full report if you need to configure each of -its subreports in a different way. - - -.SH Log report specifics - -You can enable log report with \fBlog/report_command_log\fP configuration -setting - this functionality is disabled by default. The \fBlog report\fP -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: - -.RS - -.IP \[bu] 3 -\fBlog\fP representing log report -.RS -.IP - 3 -log/command_log_cols -.IP - 3 -log/command_log_sort -.IP - 3 -log/command_log_selection -.RE - -.RE - -You always need to use \fB--configreport log\fP together with \fB-o|--options, --O|--sort or -S|--selection\fP to override configuration settings directly on -command line for \fBlog report\fP. When compared to \fBmain report\fP, in -addition to usual configuration settings for report fields and sorting, the -\fBlog report\fP has also configuration option for selection - -\fBreport/command_log_selection\fP. This configuration setting is provided for -convenience so it's not necessary to use \fB-S|--select\fP on command line -each time an LVM command is executed and we need the same selection criteria -to be applied for \fBlog report\fP. Default selection criteria used for -\fBlog report\fP are -\fBlog/command_log_selection="!(log_type=status && message=success)"\fP. -This means that, by default, \fBlog report\fP 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 \fBlog report content\fP below). - -.B Log report coverage -.br -Currently, when running LVM commands directly (not in LVM shell), the log -report covers command's \fBprocessing stage\fP 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 \fBlog report\fP. By default, that is \fBstandard error output\fP -for error and warning messages and \fBstandard output\fP for common print-like -messages. - -When running LVM commands in \fBLVM shell\fP, the log report covers the whole -LVM command's execution, including command's \fBprocessing\fP as well as -\fBinitialization\fP and \fBfinalization stage\fP. 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 \fBLVM shell\fP needs to prepare \fBlog report\fP 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 -\fBlog report\fP and display messages on output directly. - -For these reasons and for completeness, it's not possible to rely fully on -\fBlog report\fP 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 \fBcustom file descriptor\fP 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 \fBLVM_OUT_FD\fP, \fBLVM_ERR_FD\fP and -\fBLVM_REPORT_FD\fP environment variable description in \fBlvm\fP(8) -man page. - -Also note that, by default, reports use the same file descriptor as -common print-like messages, which is \fBstandard output\fP. If you plan to -use \fBlog report\fP in your scripts or any external tool, you should use -\fBLVM_OUT_FD\fP, \fBLVM_ERR_FD\fP and \fBLVM_REPORT_FD\fP to separate all -output types to different file descriptors. For example, with bash, that -would be: - -.RS -LVM_OUT_FD=3 LVM_ERR_FD=4 LVM_REPORT_FD=5 3>out_file 4>err_file 5>report_file -.RE - -Where the is either direct LVM command or LVM shell. -You can collect all three types of output in particular files then. - -.B Log report content -.br -Each item in the log report consists of these set of fields providing various -information: - -.RS - -.IP \[bu] 3 -Basic information (mandatory): -.RS -.IP - 3 -log_seq_num -.br -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. - -.IP - 3 -log_type -.br -Type of log for the item. Currently, these types are used: -.RS -.IP -\fBstatus\fP for any status information that is logged -.IP -\fBprint\fP for any common message printed while the log is collected -.IP -\fBerror\fP for any error message printed while the log is collected -.IP -\fBwarn\fP for any warning message printed while the log is collected -.RE - -.IP - 3 -log_context -.br -Context of the log for the item. Currently, two contexts are identified: -.RS -.IP -\fBshell\fP for the log collected in the outermost code before and after -executing concrete LVM commands -.IP -\fBprocessing\fP for the log collected while processing LVM entities during -LVM command execution -.RE - -.RE - -.IP \[bu] 3 -Message (mandatory): -.RS -.IP - 3 -log_message -.br -Any message associated with current item. For \fBstatus\fP log type, -the message contains either \fBsuccess\fP or \fBfailure\fP denoting -current state. For \fBprint\fP, \fBerror\fP and \fBwarn\fP log types, -the message contains the exact message of that type that got issued. -.RE - -.IP \[bu] 3 -Object information (used only if applicable): -.RS -.IP - 3 -log_object_type field -.br -Type of the object processed. Currently, these object types are recognized: -.RS -.IP -\fBcmd\fP for command as a whole -.IP -\fBorphan\fP for processing group of PVs not in any VG yet -.IP -\fBpv\fP for PV processing -.IP -\fBlabel\fP for direct PV label processing (without VG metadata) -.IP -\fBvg\fP for VG processing -.IP -\fBlv\fP for LV processing -.RE - -.IP - 3 -log_object_name -.br -Name of the object processed. - -.IP - 3 -log_object_id -.br -ID of the object processed. - -.IP - 3 -log_object_group -.br -A group where the processed object belongs to. - -.IP - 3 -log_object_group_id -.br -An ID of a group where the processed object belongs to. -.RE - -.IP \[bu] 3 -Numeric status (used only if applicable) -.RS -.IP - 3 -log_errno -.br -Error number associated with current item. -.IP - 3 -log_ret_code -.br -Rreturn code associated with current item. -.RE - -.RE - - -You can also run \fB --configreport log -o help\fP to -to display complete list of fields that you may use for the \fBlog report\fP. - -.SH Selection -Selection is used for a report to display only rows that match -\fBselection criteria\fP. All rows are displayed with the additional -\fBselected\fP field (\fB-o selected\fP) displaying 1 if the row matches the -\fISelection\fP and 0 otherwise. The \fBselection criteria\fP are a set of -\fBstatements\fP combined by \fBlogical and grouping operators\fP. -The \fBstatement\fP consists of a \fBfield\fP name for which a set of valid -\fBvalues\fP is defined using \fBcomparison operators\fP. For complete list -of fields names that you can use in selection, see the output of -\fB -S help\fP. The help output also contains type of values -that each field displays enclosed in brackets. - -.B List of operators recognized in selection criteria -.RS -.IP \[bu] 3 -Comparison operators (cmp_op) -.RS -.IP -\fB=~\fP matching regular expression. -.IP -\fB!~\fP not matching regular expression. -.IP -\fB= \fP equal to. -.IP -\fB!=\fP not equal to. -.IP -\fB>=\fP greater than or equal to. -.IP -\fB> \fP greater than -.IP -\fB<=\fP less than or equal to. -.IP -\fB< \fP less than. -.RE - -.IP \[bu] 3 -Binary logical operators (cmp_log) -.RS -.IP -\fB&&\fP all fields must match -.IP -\fB, \fP all fields must match -.IP -\fB||\fP at least one field must match -.IP -\fB# \fP@least one field must match -.RE - -.IP \[bu] 3 -Unary logical operators -.RS -.IP -\fB! \fP logical negation -.RE - -.IP \[bu] 3 -Grouping operators -.RS -.IP -\fB( \fP left parenthesis -.IP -\fB) \fP right parenthesis -.IP -\fB[ \fP list start -.IP -\fB] \fP list end -.IP -\fB{ \fP list subset start -.IP -\fB} \fP list subset end -.RE - -.RE - -.B Field types and selection operands -.br -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 \fB -S help\fP where you can find the type name -enclosed in square brackets. Currently, LVM recognizes these field types in -reports: - -.RS -.IP \[bu] 3 -\fBstring\fP 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) -.IP \[bu] 3 -\fBstring list\fP for set of strings -.IP \[bu] 3 -\fBnumber\fP for integer value -.IP \[bu] 3 -\fBsize\fP for integer or floating point number with size unit suffix -(see also \fBlvcreate\fP(8) man page and description for "-L|--size" -option for the list of recognized suffixes) -.IP \[bu] 3 -\fBpercent\fP for floating point number with or without "%" suffix -(e.g. 50 or 50%) -.IP \[bu] 3 -\fBtime\fP for time values -.RE - -When using \fBstring list\fP 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. - -.RS -.IP \[bu] 3 -\fBmatching the set strictly\fP where all items must match - use [ ], e.g. -["a","b","c"] -.IP \[bu] 3 -\fBmatching a subset of the set\fP - use { } with "," or "&&" as item -delimiter, e.g. {"a","b","c"} -.IP \[bu] 3 -\fBmatching an intersection with the set\fP - use { } with "#" or -"||" as item delimiter, e.g. {"a" || "b" || "c"} -.RE - -When using \fBtime\fP 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 \fBEXAMPLES\fP section. - -.RS - -.IP \[bu] 3 -\fBStandard time format\fP - -.RS -.IP - 3 -date -.RS -.IP -YYYY-MM-DD -.IP -YYYY-MM, auto DD=1 -.IP -YYYY, auto MM=01 and DD=01 -.RE - -.IP - 3 -time -.RS -.IP -hh:mm:ss -.IP -hh:mm, auto ss=0 -.IP -hh, auto mm=0, auto ss=0 -.RE - -.IP - 3 -timezone -.RS -.IP -+hh:mm or -hh:mm -.IP -+hh or -hh -.RE - -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: - -.RS -.IP -"2015-07-07 9:51" means range of "2015-07-07 9:51:00" - "2015-07-07 9:51:59". -.IP -"2015-07" means range of "2015-07-01 0:00:00" - "2015-07-31 23:59:59" -.IP -"2015" means range of "2015-01-01 0:00:00" - "2015-12-31 23:59:59" -.RE - -.RE - -.IP \[bu] 3 -\fBAbsolute time format\fP - -Absolute time is defined as number of seconds since the Epoch -(1970:01:01 00:00 +00:00). - -.RS -.IP - 3 - at seconds -.RE - -.IP \[bu] 3 -\fBFreeform time format\fP -.RS -.IP - 3 -weekday names ("Sunday" - "Saturday" or abbreviated as "Sun" - "Sat") -.IP - 3 -labels for points in time ("noon", "midnight") -.IP - 3 -labels for a day relative to current day ("today", "yesterday") -.IP - 3 -points back in time with relative offset from today (N is a number) -.RS -.IP -"N" "seconds" / "minutes" / "hours" / "days" / "weeks" / "years" "ago" -.IP -"N" "secs" / "mins" / "hrs" ... "ago" -.IP -"N" "s" / "m" / "h" ... "ago" -.RE -.IP - 3 -time specification either in hh:mm:ss format or with AM/PM suffixes -.IP - 3 -month names ("January" - "December" or abbreviated as "Jan" - "Dec") -.RE - -.RE - -.B Informal grammar specification -.RS -.IP -.BR STATEMENT " = " column " cmp_op " VALUE " | " \%STATEMENT " log_op " STATEMENT " | " \%(STATEMENT) " | " \%!(STATEMENT) -.IP -.BR VALUE " = " [VALUE " log_op " VALUE] -.br -For list-based types: string list. Matches strictly. -The log_op must always be of one type within the whole list value. -.IP -.BR VALUE " = " {VALUE " log_op " VALUE} -.br -For list-based types: string list. Matches a subset. -The log_op must always be of one type within the whole list value. -.IP -.BR VALUE " = " value -.br -For scalar types: number, size, percent, string (or string regex). -.RE - -.SH EXAMPLES - -.SS Basic usage - -We start our examples with default configuration - \fBlvmconfig\fP(8) is -helpful command to display configuration settings which are currently used, -including all configuration related to reporting. We will use it throughout -examples below to display current configuration. - -.nf -# lvmconfig --type full global/units global/suffix \\ - report/output_format report/compact_output \\ - report/compact_output_cols report/aligned \\ - report/headings report/separator \\ - report/list_item_separator report/prefixes \\ - report/quoted report/columns_as_rows \\ - report/binary_values_as_numeric report/time_format \\ - report/mark_hidden_devices report/two_word_unknown_device \\ - report/buffered -units="h" -suffix=1 -output_format="basic" -compact_output=0 -compact_output_cols="" -aligned=1 -headings=1 -separator=" " -list_item_separator="," -prefixes=0 -quoted=1 -columns_as_rows=0 -binary_values_as_numeric=0 -time_format="%Y-%m-%d %T %z" -mark_hidden_devices=1 -two_word_unknown_device=0 -buffered=1 -.fi - -Also, we start with simple LVM layout with two PVs (/dev/sda, /dev/sdb), -VG (vg) and two LVs (lvol0 and lvol1) in the VG. We display all possible -reports as single commands here, see also \fBpvs\fP(8), \fBvgs\fP(8), -\fBlvs\fP(8) man pages for more information. The field set for each report -type is configured with configuration settings as we already mentioned in -\fBmain report specifics\fP section in this man page. - -.nf -# lvmconfig --type full report/pvs_cols report/pvs_sort \\ - report/pvsegs_cols report/pvsegs_sort report/vgs_cols \\ - report/vgs_sort report/lvs_cols report/lvs_sort \\ - report/segs_cols report/segs_sort -pvs_cols="pv_name,vg_name,pv_fmt,pv_attr,pv_size,pv_free" -pvs_sort="pv_name" -pvsegs_cols="pv_name,vg_name,pv_fmt,pv_attr,pv_size,pv_free, - pvseg_start,pvseg_size" -pvsegs_sort="pv_name,pvseg_start" -vgs_cols="vg_name,pv_count,lv_count,snap_count,vg_attr,vg_size,vg_free" -vgs_sort="vg_name" -lvs_cols="lv_name,vg_name,lv_attr,lv_size,pool_lv,origin,move_pv, - mirror_log,copy_percent,convert_lv" -lvs_sort="vg_name,lv_name" -segs_cols="lv_name,vg_name,lv_attr,stripes,segtype,seg_size" -segs_sort="vg_name,lv_name,seg_start" -.fi - -.nf -# pvs - PV VG Fmt Attr PSize PFree - /dev/sda vg lvm2 a-- 100.00m 88.00m - /dev/sdb vg lvm2 a-- 100.00m 92.00m - -# pvs --segments - PV VG Fmt Attr PSize PFree Start SSize - /dev/sda vg lvm2 a-- 100.00m 88.00m 0 1 - /dev/sda vg lvm2 a-- 100.00m 88.00m 1 1 - /dev/sda vg lvm2 a-- 100.00m 88.00m 2 1 - /dev/sda vg lvm2 a-- 100.00m 88.00m 3 22 - /dev/sdb vg lvm2 a-- 100.00m 92.00m 0 1 - /dev/sdb vg lvm2 a-- 100.00m 92.00m 1 1 - /dev/sdb vg lvm2 a-- 100.00m 92.00m 2 23 - -# vgs - VG #PV #LV #SN Attr VSize VFree - vg 2 2 0 wz--n- 200.00m 180.00m - -# lvs - LV VG Attr LSize Pool Origin Move Log Cpy%Sync Convert - lvol0 vg -wi-a----- 4.00m - lvol1 vg rwi-a-r--- 4.00m 100.00 - -# lvs --segments - LV VG Attr #Str Type SSize - lvol0 vg -wi-a----- 1 linear 4.00m - lvol1 vg rwi-a-r--- 2 raid1 4.00m -.fi - -We will use \fBreport/lvs_cols\fP and \fBreport/lvs_sort\fP configuration -settings to define our own list of fields to use and to sort by that is -different from defaults. You can do this for other reports in same manner -with \fBreport/{pvs,pvseg,vgs,seg}_{cols,sort}\fP configuration settings. -Also note that in the example below, we don't display the "lv_time" field -even though we're using it for sorting - this is allowed. - -.nf -# lvmconfig --type full report/lvs_cols report/lvs_sort -lvs_cols="lv_name,lv_size,origin,pool_lv,copy_percent" -lvs_sort="-lv_time" - -# lvs - LV LSize Origin Pool Cpy%Sync - lvol1 4.00m 100.00 - lvol0 4.00m -.fi - -You can use \fB-o|--options\fP command line option to override current -configuration directly on command line. - -.nf -# lvs -o lv_name,lv_size - LV LSize - lvol1 4.00m - lvol0 4.00m - -# lvs -o+lv_layout - LV LSize Origin Pool Cpy%Sync Layout - lvol1 4.00m 100.00 raid,raid1 - lvol0 4.00m linear - -# lvs -o-origin - LV LSize Pool Cpy%Sync - lvol1 4.00m 100.00 - lvol0 4.00m - -# lvs -o lv_name,lv_size,origin -o+lv_layout -o-origin -O lv_name - LV LSize Layout - lvol0 4.00m linear - lvol1 4.00m raid,raid1 -.fi - -You can obtain the same information with single command where all the -information about PVs, PV segments, LVs and LV segments are obtained -per VG under a single VG lock for consistency, see also \fBlvm fullreport\fP(8) -man page for more information. The fullreport has its own configuration -settings to define field sets to use, similar to individual reports as -displayed above, but configuration settings have "_full" suffix now. -This way, it's possible to configure different sets of fields to display -and to sort by for individual reports as well as the full report. - -.nf -# lvmconfig --type full report/pvs_cols_full \\ - report/pvs_sort_full report/pvsegs_cols_full \\ - report/pvsegs_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 -pvs_cols_full="pv_name,vg_name" -pvs_sort_full="pv_name" -pvsegs_cols_full="pv_name,pvseg_start,pvseg_size" -pvsegs_sort_full="pv_uuid,pvseg_start" -vgs_cols_full="vg_name" -vgs_sort_full="vg_name" -lvs_cols_full="lv_name,vg_name" -lvs_sort_full="vg_name,lv_name" -segs_cols_full="lv_name,seg_start,seg_size" -segs_sort_full="lv_uuid,seg_start" -.fi - -.nf -# lvm fullreport - VG - vg - PV VG - /dev/sda vg - /dev/sdb vg - LV VG - lvol0 vg - lvol1 vg - PV Start SSize - /dev/sda 0 1 - /dev/sda 1 1 - /dev/sda 2 1 - /dev/sda 3 22 - /dev/sdb 0 1 - /dev/sdb 1 1 - /dev/sdb 2 23 - LV Start SSize - lvol0 0 4.00m - lvol1 0 4.00m -.fi - -.SS Automatic output compaction - -If you look at the lvs output above, you can see that the report also contains -fields for which there is no information to display (e.g. the columns under -"Origin" and "Pool" heading - the "origin" and "pool_lv" fields). LVM can -automatically compact report output so such fields are not included in final -output. To enable this feature and to compact all fields, use -\fBreport/compact_output=1\fP in your configuration. - -.nf -# lvmconfig --type full report/compact_output -compact_output=1 - -# lvs - LV LSize Cpy%Sync - lvol1 4.00m 100.00 - lvol0 4.00m - -# lvs vg/lvol0 - LV LSize - lvol0 4.00m -.fi - -Alternatively, you can define which fields should be compacted by configuring -\fBreport/compact_output_cols\fP configuration setting (or \fB-o|--options #\fP -command line option). - -.nf -# lvmconfig --type full report/compact_output report/compact_output_cols -compact_output=0 -compact_output_cols="origin" - -# lvs - LV LSize Pool Cpy%Sync - lvol1 4.00m 100.00 - lvol0 4.00m - -# lvs vg/lvol0 - LV LSize Pool - lvol0 4.00m - -# lvs -o#pool_lv - LV LSize Origin Cpy%Sync - lvol1 4.00m 100.00 - lvol0 4.00m -.fi - -We will use \fBreport/compact_output=1\fP for subsequent examples. - -.SS Further formatting options - -By default, LVM displays sizes in reports in human-readable form which means -that the most suitable unit is used so it's easy to read. You can use -\fBreport/units\fP configuration setting (or \fB--units\fP option directly -on command line) and \fBreport/suffix\fP -configuration setting (or \fB--nosuffix\fP command line option) to change this. - -.nf -# lvs --units b --nosuffix - LV LSize Cpy%Sync - lvol1 4194304 100.00 - lvol0 4194304 -.fi - -If you want to configure whether report headings are displayed or not, use -\fBreport/headings\fP configuration settings (or \fB--noheadings\fP command -line option). - -.nf -# lvs --noheadings - lvol1 4.00m 100.00 - lvol0 4.00m -.fi - -In some cases, it may be useful to display report content as key=value pairs -where key here is actually the field name. Use \fBreport/prefixes\fP -configuration setting (or \fB--nameprefixes\fP command line option) to switch -between standard output and the key=value output. The key=value pair is the -output that is suitable for use in scripts and for other tools to parse easily. -Usually, you also don't want to display headings with the output that has these -key=value pairs. - -.nf -# lvs --noheadings --nameprefixes - LVM2_LV_NAME='lvol1' LVM2_LV_SIZE='4.00m' LVM2_COPY_PERCENT='100.00' - LVM2_LV_NAME='lvol0' LVM2_LV_SIZE='4.00m' LVM2_COPY_PERCENT='' -.fi - -To define whether quotation marks in key=value pairs should be used or not, -use \fBreport/quoted\fP configuration setting (or \fB--unquoted\fP command -line option). - -.nf -# lvs --noheadings --nameprefixes --unquoted - LVM2_LV_NAME=lvol1 LVM2_LV_SIZE=4.00m LVM2_COPY_PERCENT=100.00 - LVM2_LV_NAME=lvol0 LVM2_LV_SIZE=4.00m LVM2_COPY_PERCENT= -.fi - -For easier parsing, you can even transpose the report so each column now -becomes a row in the output. This is done with \fBreport/output_as_rows\fP -configuration setting (or \fB--rows\fP command line option). - -.nf -# lvs --noheadings --nameprefixes --unquoted --rows - LVM2_LV_NAME=lvol1 LVM2_LV_NAME=lvol0 - LVM2_LV_SIZE=4.00m LVM2_LV_SIZE=4.00m - LVM2_COPY_PERCENT=100.00 LVM2_COPY_PERCENT= -.fi - -Use \fBreport/separator\fP configuration setting (or \fB--separator\fP command -line option) to define your own field separator to use. - -.nf -# lvs --noheadings --nameprefixes --unquoted --separator " | " - LVM2_LV_NAME=lvol1 | LVM2_LV_SIZE=4.00m | LVM2_COPY_PERCENT=100.00 - LVM2_LV_NAME=lvol0 | LVM2_LV_SIZE=4.00m | LVM2_COPY_PERCENT= -.fi - -If you are using your own separator, the columns in the output are not aligned -by default. Use \fBreport/aligned\fP configuration setting (or \fB--aligned\fP -command line option) for LVM to add extra spaces in report to align the output -properly. - -.nf -# lvs --separator " | " - LV | LSize | Cpy%Sync - lvol1 | 4.00m | 100.00 - lvol0 | 4.00m | - -# lvs --separator " | " --aligned - LV | LSize | Cpy%Sync - lvol1 | 4.00m | 100.00 - lvol0 | 4.00m | -.fi - -Let's display one one more field in addition ("lv_tags" in this example) -for the lvs report output. - -.nf -# lvs -o+lv_tags - LV LSize Cpy%Sync LV Tags - lvol1 4.00m 100.00 - lvol0 4.00m tagA,tagB -.fi - -The "LV Tags" column in the example above displays two list values, -separated by "," character for LV lvol0. If you need different list item -separator, use \fBreport/list_item_separator\fP configuration setting its -definition. - -.nf -# lvmconfig --type full report/list_item_separator -list_item_separator=";" - -# lvs -o+tags - LV LSize Cpy%Sync LV Tags - lvol1 4.00m 100.00 - lvol0 4.00m tagA;tagB -.fi - -But let's still use the original "," character for list_item_separator -for subsequent examples. - -Format for any of time values displayed in reports can be configured with -\fBreport/time_format\fP configuretion setting. By default complete date -and time is displayed, including timezone. - -.nf -# lvmconfig --type full report/time_format -time_format="%Y-%m-%d %T %z" - -# lvs -o+time - LV LSize Cpy%Sync CTime - lvol1 4.00m 100.00 2016-08-29 12:53:36 +0200 - lvol0 4.00m 2016-08-29 10:15:17 +0200 -.fi - -We can change time format in similar way as we do when using \fBdate\fP(1) -command or \fBstrftime\fP(3) function -(\fBlvmconfig --type default --withcomments report/time_format\fP will -give you complete list of available formatting options). In the example -below, we decided to use %s for number of seconds since Epoch (1970-01-01 UTC). - -.nf -# lvmconfig --type full report/time_format -time_format="%s" - -# lvs - LV Attr LSize Cpy%Sync LV Tags CTime - lvol1 rwi-a-r--- 4.00m 100.00 1472468016 - lvol0 -wi-a----- 4.00m tagA,tagB 1472458517 -.fi - -The \fBlvs\fP does not display hidden LVs by default - to include these LVs -in the output, you need to use \fB-a|--all\fP command line option. Names for -these hidden LVs are displayed within square brackets. - -.nf -# lvs -a - LV LSize Cpy%Sync - lvol1 4.00m 100.00 - [lvol1_rimage_0] 4.00m - [lvol1_rmeta_0] 4.00m - [lvol1_rimage_1] 4.00m - [lvol1_rmeta_1] 4.00m - lvol0 4.00m -.fi - -You can configure LVM to display the square brackets for hidden LVs or not with -\fBreport/mark_hidden_devices\fP configuration setting. - -.nf -# lvmconfig --type full report/mark_hidden_devices -mark_hidden_devices=0 - -# lvs -a - LV LSize Cpy%Sync - lvol1 4.00m 100.00 - lvol1_rimage_0 4.00m - lvol1_rmeta_0 4.00m - lvol1_rimage_1 4.00m - lvol1_rmeta_1 4.00m - lvol0 4.00m -.fi - -It's not recommended to use LV marks for hidden devices to decide whether the -LV is the one to use by end users or not. Please, use "lv_role" field instead -which can report whether the LV is "public" or "private". The private LVs are -used by LVM only and they should not be accessed directly by end users. - -.nf -# lvs -a -o+lv_role - LV LSize Cpy%Sync Role - lvol1 4.00m 100.00 public - lvol1_rimage_0 4.00m private,raid,image - lvol1_rmeta_0 4.00m private,raid,metadata - lvol1_rimage_1 4.00m private,raid,image - lvol1_rmeta_1 4.00m private,raid,metadata - lvol0 4.00m public -.fi - -Some of the reporting fields that LVM reports are of binary nature. For such -fields, it's either possible to display word representation of the value -(this is used by default) or numeric value (0/1 or -1 in case the value is -undefined). - -.nf -# lvs -o+lv_active_locally - LV LSize Cpy%Sync ActLocal - lvol1 4.00m 100.00 active locally - lvol0 4.00m active locally -.fi - -We can change the way how these binary values are displayed with -\fBreport/binary_values_as_numeric\fP configuration setting. - -.nf -# lvmconfig --type full report/binary_values_as_numeric -binary_values_as_numeric=1 - -# lvs -o+lv_active_locally - LV LSize Cpy%Sync ActLocal - lvol1 4.00m 100.00 1 - lvol0 4.00m 1 -.fi - -.SS Changing output format - -LVM can output reports in different formats - use \fBreport/output_format\fP -configuration setting (or \fB--reportformat\fP command line option) to swith -the report output format. Currently, LVM supports \fB"basic"\fP (all the examples -we used above used this format) and \fB"JSON"\fP output format. - -.nf -# lvs -o lv_name,lv_size --reportformat json - { - "report": [ - { - "lv": [ - {"lv_name":"lvol1", "lv_size":"4.00m"}, - {"lv_name":"lvol0", "lv_size":"4.00m"} - ] - } - ] - } -.fi - -Note that some configuration settings and command line options have no -effect with certain report formats. For example, with \fBJSON\fP output, -it doesn't have any meaning to use \fBreport/aligned\fP (\fB--aligned\fP), -\fBreport/noheadings\fP (\fB--noheadings\fP), \fBreport/columns_as_rows\fP -(\fB--rows\fP) or \fBreport/buffered\fP (\fB--unbuffered\fP). All these -configuration settings and command line options are ignored if using the -\fBJSON\fP report output format. - -.SS Selection - -If you need to select only specific rows from report, you can use LVM's -report selection feature. If you call \fB -S help\fP, you'll get -quick help on selection. The help contains list of all fields that LVM -can use in reports together with its type enclosed in square brackets. -The example below contains a line from lvs -S help. - -.nf -# lvs -S help - ... - lv_size - Size of LV in current units. [size] - ... -.fi - -This line tells you you that the "lv_size" field is of "size" type. If you -look at the bottom of the help output, you can see section about -"Selection operators" and its "Comparison operators". - -.nf -# lvs -S help - ... -Selection operators -------------------- -Comparison operators: - =~ - Matching regular expression. [regex] - !~ - Not matching regular expression. [regex] - = - Equal to. [number, size, percent, string, string list, time] - != - Not equal to. [number, size, percent, string, string_list, time] - >= - Greater than or equal to. [number, size, percent, time] - > - Greater than. [number, size, percent, time] - <= - Less than or equal to. [number, size, percent, time] - < - Less than. [number, size, percent, time] -since - Since specified time (same as '>='). [time] -after - After specified time (same as '>'). [time] -until - Until specified time (same as '<='). [time] -before - Before specified time (same as '<'). [time] - ... -.fi - -Here you can match comparison operators that you may use with the "lv_size" -field which is of type "size" - it's =, !=, >=, >, <= and <. You can find -applicable comparison operators for other fields and other field types the -same way. - -To demostrate selection functionality in LVM, we will create more LVs in -addition to lvol0 and lvol1 we used in our previous examples. - -.nf -# lvs -o name,size,origin,snap_percent,tags,time - LV LSize Origin Snap% LV Tags CTime - lvol4 4.00m lvol2 24.61 2016-09-09 16:57:44 +0200 - lvol3 4.00m lvol2 5.08 2016-09-09 16:56:48 +0200 - lvol2 8.00m tagA,tagC,tagD 2016-09-09 16:55:12 +0200 - lvol1 4.00m 2016-08-29 12:53:36 +0200 - lvol0 4.00m tagA,tagB 2016-08-29 10:15:17 +0200 -.fi - -When selecting size and percent fields, we don't need to use units. -For sizes, default "m" (for MiB) is used - this is the same behaviour -as already used for LVM commands when specifying sizes (e.g. lvcreate -L). -For percent fields, "%" is assumed automatically if it's not specified. -The example below also demonstrates how several criteria can be combined -together. - -.nf -# lvs -o name,size,snap_percent -S 'size=8m' - LV LSize - lvol2 8.00m - -# lvs -o name,size,snap_percent -S 'size=8' - LV LSize - lvol2 8.00m - -# lvs -o name,size,snap_percent -S 'size < 5000k' - LV LSize Snap% - lvol4 4.00m 24.61 - lvol3 4.00m 5.08 - lvol1 4.00m - lvol0 4.00m - -# lvs -o name,size,snap_percent -S 'size < 5000k && snap_percent > 20' - LV LSize Snap% - lvol4 4.00m 24.61 - -# lvs -o name,size,snap_percent \\ - -S '(size < 5000k && snap_percent > 20%) || name=lvol2' - LV LSize Snap% - lvol4 4.00m 24.61 - lvol2 8.00m -.fi - -You can also use selection together with processing-oriented commands. - -.nf -# lvchange --addtag test -S 'size < 5000k' - Logical volume vg/lvol1 changed. - Logical volume vg/lvol0 changed. - Logical volume vg/lvol3 changed. - Logical volume vg/lvol4 changed. - -# lvchange --deltag test -S 'tags = test' - Logical volume vg/lvol1 changed. - Logical volume vg/lvol0 changed. - Logical volume vg/lvol3 changed. - Logical volume vg/lvol4 changed. -.fi - -LVM can recognize more complex values used in selection criteria for -string list and time field types. For string lists, you can match -whole list strictly, its subset or intersection. Let's take "lv_tags" -field as an example - we select only rows which contain "tagA" within -tags field. We're using { } to denote that we're interested in subset -that matches. If the subset has only one item, we can leave out { }. - -.nf -# lvs -o name,tags -S 'tags={tagA}' - LV LV Tags - lvol2 tagA,tagC,tagD - lvol0 tagA,tagB - -# lvs -o name,tags -S 'tags=tagA' - LV LV Tags - lvol2 tagA,tagC,tagD - lvol0 tagA,tagB -.fi - -Depending on whether we use "&&" (or ",") or "||" ( or "#") as delimiter -for items in the set we define in selection criterion for string list, -we either match subset ("&&" or ",") or even intersection ("||" or "#"). - -.nf -# lvs -o name,tags -S 'tags={tagA,tagC,tagD}' - LV LV Tags - lvol2 tagA,tagC,tagD - -# lvs -o name,tags -S 'tags={tagA || tagC || tagD}' - LV LV Tags - lvol2 tagA,tagC,tagD - lvol0 tagA,tagB -.fi - -To match the complete set, use [ ] with "&&" (or ",") as delimiter for items. -Also note that the order in which we define items in the set is not relevant. - -.nf -# lvs -o name,tags -S 'tags=[tagA]' - -# lvs -o name,tags -S 'tags=[tagB,tagA]' - LV LV Tags - lvol0 tagA,tagB -.fi - -If you use [ ] with "||" (or "#"), this is exactly the same as using { }. - -.nf -# lvs -o name,tags -S 'tags=[tagA || tagC || tagD]' - LV LV Tags - lvol2 tagA,tagC,tagD - lvol0 tagA,tagB -.fi - -To match a set with no items, use "" to denote this (note that we have -output compaction enabled so the "LV Tags" column is not displayed in -the example below because it's blank and so it gets compacted). - -.nf -# lvs -o name,tags -S 'tags=""' - LV - lvol4 - lvol3 - lvol1 - -# lvs -o name,tags -S 'tags!=""' - LV LV Tags - lvol2 tagA,tagC,tagD - lvol0 tagA,tagB -.fi - -When doing selection based on time fields, we can use either standard, -absolute or freeform time expressions in selection criteria. Examples below -are using standard forms. - -.nf -# lvs -o name,time - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - lvol3 2016-09-09 16:56:48 +0200 - lvol2 2016-09-09 16:55:12 +0200 - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 - -# lvs -o name,time -S 'time since "2016-09-01"' - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - lvol3 2016-09-09 16:56:48 +0200 - lvol2 2016-09-09 16:55:12 +0200 - -# lvs -o name,time -S 'time since "2016-09-09 16:56"' - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - lvol3 2016-09-09 16:56:48 +0200 - -# lvs -o name,time -S 'time since "2016-09-09 16:57:30"' - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - -# lvs -o name,time \\ - -S 'time since "2016-08-29" && time until "2016-09-09 16:55:12"' - LV CTime - lvol2 2016-09-09 16:55:12 +0200 - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 - -# lvs -o name,time \\ - -S 'time since "2016-08-29" && time before "2016-09-09 16:55:12"' - LV CTime - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 -.fi - -Time operators have synonyms: ">=" for since, "<=" for until, -">" for "after" and "<" for "before". - -.nf -# lvs -o name,time \\ - -S 'time >= "2016-08-29" && time <= "2016-09-09 16:55:30"' - LV CTime - lvol2 2016-09-09 16:55:12 +0200 - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 - -# lvs -o name,time \\ - -S 'time since "2016-08-29" && time < "2016-09-09 16:55:12"' - LV CTime - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 -.fi - -Example below demonstrates using absolute time expression. - -.nf -# lvs -o name,time --config report/time_format="%s" - LV CTime - lvol4 1473433064 - lvol3 1473433008 - lvol2 1473432912 - lvol1 1472468016 - lvol0 1472458517 - -# lvs -o name,time -S 'time since @1473433008' - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - lvol3 2016-09-09 16:56:48 +0200 -.fi - -Examples below demonstrates using freeform time expressions. - -.nf -# lvs -o name,time -S 'time since "2 weeks ago"' - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - lvol3 2016-09-09 16:56:48 +0200 - lvol2 2016-09-09 16:55:12 +0200 - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 - -# lvs -o name,time -S 'time since "1 week ago"' - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - lvol3 2016-09-09 16:56:48 +0200 - lvol2 2016-09-09 16:55:12 +0200 - -# lvs -o name,time -S 'time since "2 weeks ago"' - LV CTime - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 - -# lvs -o name,time -S 'time before "1 week ago"' - LV CTime - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 - -# lvs -o name,time -S 'time since "68 hours ago"' - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - lvol3 2016-09-09 16:56:48 +0200 - lvol2 2016-09-09 16:55:12 +0200 - -# lvs -o name,time -S 'time since "1 year 3 months ago"' - LV CTime - lvol4 2016-09-09 16:57:44 +0200 - lvol3 2016-09-09 16:56:48 +0200 - lvol2 2016-09-09 16:55:12 +0200 - lvol1 2016-08-29 12:53:36 +0200 - lvol0 2016-08-29 10:15:17 +0200 -.fi - -.SS Command log reporting - -As described in \fBcategorization based on reporting facility\fP section -at the beginning of this document, both \fBreport-oriented\fP and -\fBprocessing-oriented\fP LVM commands can report the command log if -this is enabled with \fBlog/report_command_log\fP configuration setting. -Just like any other report, we can set the set of fields to display -(\fBlog/command_log_cols\fP) and to sort by (\fBlog/command_log_sort\fP) -for this report. - -.nf -# lvmconfig --type full log/report_command_log log/command_log_cols \\ - log/command_log_sort log/command_log_selection -report_command_log=1 -command_log_cols="log_seq_num,log_type,log_context,log_object_type, - log_object_name,log_object_group,log_message, - log_errno,log_ret_code" -command_log_sort="log_seq_num" -command_log_selection="!(log_type=status && message=success)" - - -# lvs - Logical Volume - ============== - LV LSize Cpy%Sync - lvol1 4.00m 100.00 - lvol0 4.00m - - Command Log - =========== - Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode -.fi - -As you can see, the command log is empty (it contains only field names). -By default, LVM uses selection on the command log report and this case -no row matched the selection criteria, see also \fBlog report specifics\fP -section in this document for more information. We're displaying complete -log report in the example below where we can see that both LVs lvol0 and -lvol1 were successfully processed as well as the VG vg they are part of. - -.nf -# lvmconfig --type full log/command_log_selection -command_log_selection="all" - -# lvs - Logical Volume - ============== - LV LSize Cpy%Sync - lvol1 4.00m 100.00 - lvol0 4.00m - - Command Log - =========== - Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode - 1 status processing lv lvol0 vg success 0 1 - 2 status processing lv lvol1 vg success 0 1 - 3 status processing vg vg success 0 1 - -# lvchange -an vg/lvol1 - Command Log - =========== - Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode - 1 status processing lv lvol1 vg success 0 1 - 2 status processing vg vg success 0 1 -.fi - -.SS Handling multiple reports per single command - -To configure the log report directly on command line, we need to use -\fB--configreport\fP option before we start any \fB-o|--options\fP, -\fB-O|--sort\fP or \fB-S|--select\fP that is targeted for log report. - -.nf -# lvs -o lv_name,lv_size --configreport log -o log_object_type, \\ - log_object_name,log_message,log_ret_code - Logical Volume - ============== - LV LSize - lvol1 4.00m - lvol0 4.00m - - Command Log - =========== - ObjType ObjName Msg RetCode - lv lvol0 success 1 - lv lvol1 success 1 - vg vg success 1 -.fi - -The \fBlvm fullreport\fP, with or without log report, consists of several -reports - the \fB--configreport\fP is also used to target particular -subreport here. - -Below is an extended example with \fBlvm fullreport\fP to illustrate -combination of various options. The report output is in JSON format. -Also, we configure "vg", "pvseg", "seg" and "log" subreport to contain -only specified fields. For the "pvseg" subreport, we're intested only -in PV names having "sda" in their name. For the "log" subreport we're -intested only in log lines related to either "lvol0" object or object -having "sda" in its name. Also, for the log subreport we define ordering -to be based on "log_object_type" field. - -.nf -# lvm fullreport --reportformat json \\ - --configreport vg -o vg_name,vg_size \\ - --configreport pvseg -o pv_name,pvseg_start \\ - -S 'pv_name=~sda' \\ - --configreport seg -o lv_name,seg_start \\ - --configreport log -o log_object_type,log_object_name \\ - -O log_object_type \\ - -S 'log_object_name=lvol0 || \\ - log_object_name=~sda' - { - "report": [ - { - "vg": [ - {"vg_name":"vg", "vg_size":"200.00m"} - ] - , - "pv": [ - {"pv_name":"/dev/sda", "vg_name":"vg"}, - {"pv_name":"/dev/sdb", "vg_name":"vg"} - ] - , - "lv": [ - {"lv_name":"lvol0", "vg_name":"vg"}, - {"lv_name":"lvol1", "vg_name":"vg"} - ] - , - "pvseg": [ - {"pv_name":"/dev/sda", "pvseg_start":"0"}, - {"pv_name":"/dev/sda", "pvseg_start":"1"}, - {"pv_name":"/dev/sda", "pvseg_start":"2"}, - {"pv_name":"/dev/sda", "pvseg_start":"3"} - ] - , - "seg": [ - {"lv_name":"lvol0", "seg_start":"0 "}, - {"lv_name":"lvol1", "seg_start":"0 "} - ] - } - ] - , - "log": [ - {"log_object_type":"lv", "log_object_name":"lvol0"}, - {"log_object_type":"lv", "log_object_name":"lvol0"}, - {"log_object_type":"pv", "log_object_name":"/dev/sda"}, - {"log_object_type":"pv", "log_object_name":"/dev/sda"}, - ] - } -.fi - -.SS Report extensions for LVM shell - -As already stated in \fBlog report coverage\fP paragraph under -\fBlog report specifics\fP in this documentation, when using \fBLVM shell\fP -the \fBlog report\fP coverage is wider. There's also special command -designed to query last command's log report in the \fBLVM shell\fP - -the \fBlastlog\fP command. - -The example below illustrates a situation where we called lvs command. -After that, we inspected the log report with the \fBlastlog\fP, without -any selection so all the log report is displayed on output. Then we called -\fBlastlog\fP further, giving various selection criteria. Then we ran -unknown LVM command "abc" for which the log report displays appropriate -failure state. - -.nf -# lvm -lvm> lvs - Logical Volume - ============== - LV LSize Cpy%Sync - lvol1 4.00m 100.00 - lvol0 4.00m - - Command Log - =========== - Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode - 1 status processing lv lvol0 vg success 0 1 - 2 status processing lv lvol1 vg success 0 1 - 3 status processing vg vg success 0 1 - 4 status shell cmd lvs success 0 1 - -lvm> lastlog - Command Log - =========== - Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode - 1 status processing lv lvol0 vg success 0 1 - 2 status processing lv lvol1 vg success 0 1 - 3 status processing vg vg success 0 1 - 4 status shell cmd lvs success 0 1 - -lvm> lastlog -S log_object_type=lv - Command Log - =========== - Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode - 1 status processing lv lvol0 vg success 0 1 - 2 status processing lv lvol1 vg success 0 1 - -lvm> lastlog -S log_context=shell - Command Log - =========== - Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode - 4 status shell cmd lvs success 0 1 - -lvm> abc - Command Log - =========== - Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode - 1 error shell cmd abc No such command 'abc'. Try 'help'. -1 0 - 2 status shell cmd abc failure -1 2 -.fi - -.SH SEE ALSO -\fBlvm\fP (8), -\fBlvmconfig\fP (8), -\fBlvm fullreport\fP (8) diff --git a/man/lvmreport.7_main b/man/lvmreport.7_main new file mode 100644 index 0000000..7a26401 --- /dev/null +++ b/man/lvmreport.7_main @@ -0,0 +1,1810 @@ +.TH "LVMREPORT" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" + +.SH NAME +lvmreport \(em LVM reporting and related features + +.SH DESCRIPTION +LVM uses single reporting infrastructure that sets standard on LVM command's +output and it provides wide range of configuration settings and command line +options to customize report and filter the report's output. + +.SH Categorization based on reporting facility + +Based on functionality, commands which make use of the reporting infrastructure +are divided in two groups: +.IP \fBReport-oriented commands\fP +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 \fBmain report\fP. The set of report-only commands include: +pvs, vgs, lvs, pvdisplay, vgdisplay, lvdisplay, lvm devtypes, lvm fullreport. +For further information about main report, see \fBmain report specifics\fP. +.IP \fBProcessing-oriented commands\fP +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. + +.RE +If enabled, so called \fBlog report\fP 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 \fBlog report specifics\fP for more +information about this report type. + + +.SH Terms + +When describing reporting functionality and features in this text, we will +use terms \fBrow\fP and \fBcolumn\fP. 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 \fBcolumn headings\fP +which are short descriptions for the columns. The columns are referenced by +\fBcolumn names\fP. Please note that this text is also using term \fBfield\fP +interchangeably with the term \fBcolumn\fP. Most of the time the term columns +is abbreviated as \fBcol\fP in configuration. + +.SH Common report configuration settings and command line options + +There are common configuration settings and command line options which apply +to both \fBmain report\fP and \fBlog report\fP. Following lists contain all +of them, separated into groups based on their use. + +.RS +\fBCommon configuration settings:\fP + +.RS + +.IP \[bu] 3 +Changing report output format, composition and other output modifiers: +.RS +.IP - 3 +global/units +.IP - 3 +global/suffix +.IP - 3 +report/output_format +.IP - 3 +report/compact_output +.IP - 3 +report/compact_output_cols +.IP - 3 +report/aligned +.IP - 3 +report/headings +.IP - 3 +report/separator +.IP - 3 +report/list_item_separator +.IP - 3 +report/prefixes +.IP - 3 +report/quoted +.IP - 3 +report/columns_as_rows +.IP - 3 +report/binary_values_as_numeric +.IP - 3 +report/time_format +.IP - 3 +report/mark_hidden_devices +.IP - 3 +report/two_word_unknown_device +.RE + +.IP \[bu] 3 +Special settings +.RS +.IP - 3 +report/buffered +.RE + +.RE + +.RE + +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 \fBlvmconfig --type default --withcomments \fP. There are +more configuration settings in addition to the common set listed above, but +they are specific to either \fBmain report\fP or \fBlog report\fP, +see \fBmain report specifics\fP and \fBlog report specifics\fP 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. + +.RS +\fBCommon command line options:\fP + +.RS + +.IP \[bu] 3 +Definition of the set set of fields to use +.RS +.IP - 3 +--options|-o FieldSet +.br +Field set to use. See \fBmain report specifics\fP and +\fBlog report specifics\fP for information about field sets configured with +global configuratin settings that this option overrides. +.IP - 3 +--options|-o+ FieldSet +.br +Fields to include to current field set. See \fBmain report specifics\fP\ and +\fBlog report specifics\fP for information about field sets configured with +global configuration settings that this option extends. +.IP - 3 +--options|-o- FieldSet +.br +Fields to exclude from current field set. See \fBmain report specifics\fP and +\fBlog report specifics\fP for information about field sets configured with +global configuration settings that this option reduces. +.IP - 3 +--options|-o# FieldSet +.br +Compaction of unused fields. Overrides report/compact_output_cols configuration +setting. +.RE + +.IP \[bu] 3 +Sorting +.RS +.IP - 3 +--sort|-O+ FieldSet +.br +Fields to sort by in ascending order. See \fBmain report specifics\fP and +\fBlog report specifics\fP for information about field sets configured with +global configuration settings that this option overrides. +.IP - 3 +--sort|-O- FieldSet +.br +Fields to sort by in descending order. See \fBmain report specifics\fP and +\fBlog report specifics\fP for information about fields sets configured with +global configuration settings that this options overrides. +.RE + +.IP \[bu] 3 +Selection +.RS +.IP - 3 +--select|-S Selection +.br +Define selection criteria for report output. For \fBlog report\fP, this also +overrides log/command_log_selection configuration setting, see also +\fBlog report specifics\fP. +.RE + +.IP \[bu] 3 +Changing output format and composition +.RS +.IP - 3 +--reportformat +.br +Overrides report/output_format configuration setting. +.IP - 3 +--aligned +.br +Overrides report/aligned configuration setting. +.IP - 3 +--binary +.br +Overrides report/binary_values_as_numeric configuration setting. +.IP - 3 +--nameprefixes +.br +Overrides report/prefixes configuration setting. +.IP - 3 +--noheadings +.br +Overrides report/noheadings configuration setting. +.IP - 3 +--nosuffix +.br +Overrides global/suffix configuration setting. +.IP - 3 +--rows +.br +Overrides report/columns_as_rows configuration setting. +.IP - 3 +--separator +.br +Overrides report/separator configuration setting. +.IP - 3 +--units +.br +Overrides global/units configuration setting. +.IP - 3 +--unquoted +.br +Overrides report/quoted configuration setting. +.RE + +.IP \[bu] 3 +Special options +.RS +.IP - 3 +--configreport \fBReportName\fP +.br +This defines the \fBReportName\fP for which any subsequent -o|--columns, +-O|--sort or -S|--select applies to. See also \fBmain report specifics\fP +and \fBlog report specifics\fP for possible \fBReportName\fP values. +.IP - 3 +--logonly +.br +When an LVM command contains both \fBmain report\fP and \fBlog report\fP, +this option suppresses the \fBmain report\fP output and it causes the +\fBlog report\fP output to be displayed only. +.IP - 3 +--unbuffered +.br +Overrides report/bufffered configuration setting. +.RE + +.RE + +.RE + +The \fBFieldSet\fP 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 \fBSelection\fP +is a string with \fBselection criteria\fP, see also \fBSelection\fP paragraph +below for more information about constructing these criteria. + + +.SH Main report specifics + +The \fBmain report\fP currently encompasses these distinct subtypes, referenced +by their name - \fBReportName\fP 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 \fBReportName\fP): + +.RS + +.IP \[bu] 3 +\fBpv\fP representing report about Physical Volumes (\fBpvs\fP) +.RS +.IP - 3 +report/pvs_cols +.IP - 3 +report/pvs_sort +.RE + +.IP \[bu] 3 +\fBpvseg\fP representing report about Physical Volume Segments (\fBpvs --segments\fP) +.RS +.IP - 3 +report/pvseg_cols +.IP - 3 +report/pvseg_sort +.RE + +.IP \[bu] 3 +\fBvg\fP representing report about Volume Groups (\fBvgs\fP) +.RS +.IP - 3 +report/vgs_cols +.IP - 3 +report/vgs_sort +.RE + +.IP \[bu] 3 +\fBlv\fP representing report about Logical Volumes (\fBlvs\fP) +.RS +.IP - 3 +report/lvs_cols +.IP - 3 +report/lvs_sort +.RE + +.IP \[bu] 3 +\fBseg\fP representing report about Logical Volume Segments (\fBlvs --segments\fP) +.RS +.IP - 3 +report/segs_cols +.IP - 3 +report/segs_sort +.RE + +.IP \[bu] 3 +\fBfull\fP representing report combining all of the above as a whole (\fBlvm fullreport\fP) +.RS +.IP - 3 +report/pvs_cols_full +.IP - 3 +report/pvs_sort_full +.IP - 3 +report/pvsegs_cols_full +.IP - 3 +report/pvseg_sort_full +.IP - 3 +report/vgs_cols_full +.IP - 3 +report/vgs_sort_full +.IP - 3 +report/lvs_cols_full +.IP - 3 +report/lvs_sort_full +.IP - 3 +report/segs_cols_full +.IP - 3 +report/segs_sort_full +.RE + +.IP \[bu] 3 +\fBdevtype\fP representing report about device types (\fBlvm devtypes\fP) +.RS +.IP - 3 +report/devtypes_cols +.IP - 3 +report/devtypes_sort +.RE + +.RE + +Use \fBpvs, vgs, lvs -o help\fP or \fBlvm devtypes -o help\fP 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 \fBfull\fP, it's not necessary to use +\fB--configreport ReportName\fP to denote which report any subsequent +\fB-o, -O or -S\fP option applies to as they always apply to the single main +report type. Currently, \fBlvm fullreport\fP is the only command that +includes more than one \fBmain report\fP subtype. Therefore, the --configreport +is particularly suitable for the full report if you need to configure each of +its subreports in a different way. + + +.SH Log report specifics + +You can enable log report with \fBlog/report_command_log\fP configuration +setting - this functionality is disabled by default. The \fBlog report\fP +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: + +.RS + +.IP \[bu] 3 +\fBlog\fP representing log report +.RS +.IP - 3 +log/command_log_cols +.IP - 3 +log/command_log_sort +.IP - 3 +log/command_log_selection +.RE + +.RE + +You always need to use \fB--configreport log\fP together with \fB-o|--options, +-O|--sort or -S|--selection\fP to override configuration settings directly on +command line for \fBlog report\fP. When compared to \fBmain report\fP, in +addition to usual configuration settings for report fields and sorting, the +\fBlog report\fP has also configuration option for selection - +\fBreport/command_log_selection\fP. This configuration setting is provided for +convenience so it's not necessary to use \fB-S|--select\fP on command line +each time an LVM command is executed and we need the same selection criteria +to be applied for \fBlog report\fP. Default selection criteria used for +\fBlog report\fP are +\fBlog/command_log_selection="!(log_type=status && message=success)"\fP. +This means that, by default, \fBlog report\fP 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 \fBlog report content\fP below). + +.B Log report coverage +.br +Currently, when running LVM commands directly (not in LVM shell), the log +report covers command's \fBprocessing stage\fP 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 \fBlog report\fP. By default, that is \fBstandard error output\fP +for error and warning messages and \fBstandard output\fP for common print-like +messages. + +When running LVM commands in \fBLVM shell\fP, the log report covers the whole +LVM command's execution, including command's \fBprocessing\fP as well as +\fBinitialization\fP and \fBfinalization stage\fP. 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 \fBLVM shell\fP needs to prepare \fBlog report\fP 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 +\fBlog report\fP and display messages on output directly. + +For these reasons and for completeness, it's not possible to rely fully on +\fBlog report\fP 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 \fBcustom file descriptor\fP 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 \fBLVM_OUT_FD\fP, \fBLVM_ERR_FD\fP and +\fBLVM_REPORT_FD\fP environment variable description in \fBlvm\fP(8) +man page. + +Also note that, by default, reports use the same file descriptor as +common print-like messages, which is \fBstandard output\fP. If you plan to +use \fBlog report\fP in your scripts or any external tool, you should use +\fBLVM_OUT_FD\fP, \fBLVM_ERR_FD\fP and \fBLVM_REPORT_FD\fP to separate all +output types to different file descriptors. For example, with bash, that +would be: + +.RS +LVM_OUT_FD=3 LVM_ERR_FD=4 LVM_REPORT_FD=5 3>out_file 4>err_file 5>report_file +.RE + +Where the is either direct LVM command or LVM shell. +You can collect all three types of output in particular files then. + +.B Log report content +.br +Each item in the log report consists of these set of fields providing various +information: + +.RS + +.IP \[bu] 3 +Basic information (mandatory): +.RS +.IP - 3 +log_seq_num +.br +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. + +.IP - 3 +log_type +.br +Type of log for the item. Currently, these types are used: +.RS +.IP +\fBstatus\fP for any status information that is logged +.IP +\fBprint\fP for any common message printed while the log is collected +.IP +\fBerror\fP for any error message printed while the log is collected +.IP +\fBwarn\fP for any warning message printed while the log is collected +.RE + +.IP - 3 +log_context +.br +Context of the log for the item. Currently, two contexts are identified: +.RS +.IP +\fBshell\fP for the log collected in the outermost code before and after +executing concrete LVM commands +.IP +\fBprocessing\fP for the log collected while processing LVM entities during +LVM command execution +.RE + +.RE + +.IP \[bu] 3 +Message (mandatory): +.RS +.IP - 3 +log_message +.br +Any message associated with current item. For \fBstatus\fP log type, +the message contains either \fBsuccess\fP or \fBfailure\fP denoting +current state. For \fBprint\fP, \fBerror\fP and \fBwarn\fP log types, +the message contains the exact message of that type that got issued. +.RE + +.IP \[bu] 3 +Object information (used only if applicable): +.RS +.IP - 3 +log_object_type field +.br +Type of the object processed. Currently, these object types are recognized: +.RS +.IP +\fBcmd\fP for command as a whole +.IP +\fBorphan\fP for processing group of PVs not in any VG yet +.IP +\fBpv\fP for PV processing +.IP +\fBlabel\fP for direct PV label processing (without VG metadata) +.IP +\fBvg\fP for VG processing +.IP +\fBlv\fP for LV processing +.RE + +.IP - 3 +log_object_name +.br +Name of the object processed. + +.IP - 3 +log_object_id +.br +ID of the object processed. + +.IP - 3 +log_object_group +.br +A group where the processed object belongs to. + +.IP - 3 +log_object_group_id +.br +An ID of a group where the processed object belongs to. +.RE + +.IP \[bu] 3 +Numeric status (used only if applicable) +.RS +.IP - 3 +log_errno +.br +Error number associated with current item. +.IP - 3 +log_ret_code +.br +Rreturn code associated with current item. +.RE + +.RE + + +You can also run \fB --configreport log -o help\fP to +to display complete list of fields that you may use for the \fBlog report\fP. + +.SH Selection +Selection is used for a report to display only rows that match +\fBselection criteria\fP. All rows are displayed with the additional +\fBselected\fP field (\fB-o selected\fP) displaying 1 if the row matches the +\fISelection\fP and 0 otherwise. The \fBselection criteria\fP are a set of +\fBstatements\fP combined by \fBlogical and grouping operators\fP. +The \fBstatement\fP consists of a \fBfield\fP name for which a set of valid +\fBvalues\fP is defined using \fBcomparison operators\fP. For complete list +of fields names that you can use in selection, see the output of +\fB -S help\fP. The help output also contains type of values +that each field displays enclosed in brackets. + +.B List of operators recognized in selection criteria +.RS +.IP \[bu] 3 +Comparison operators (cmp_op) +.RS +.IP +\fB=~\fP matching regular expression. +.IP +\fB!~\fP not matching regular expression. +.IP +\fB= \fP equal to. +.IP +\fB!=\fP not equal to. +.IP +\fB>=\fP greater than or equal to. +.IP +\fB> \fP greater than +.IP +\fB<=\fP less than or equal to. +.IP +\fB< \fP less than. +.RE + +.IP \[bu] 3 +Binary logical operators (cmp_log) +.RS +.IP +\fB&&\fP all fields must match +.IP +\fB, \fP all fields must match +.IP +\fB||\fP at least one field must match +.IP +\fB# \fP@least one field must match +.RE + +.IP \[bu] 3 +Unary logical operators +.RS +.IP +\fB! \fP logical negation +.RE + +.IP \[bu] 3 +Grouping operators +.RS +.IP +\fB( \fP left parenthesis +.IP +\fB) \fP right parenthesis +.IP +\fB[ \fP list start +.IP +\fB] \fP list end +.IP +\fB{ \fP list subset start +.IP +\fB} \fP list subset end +.RE + +.RE + +.B Field types and selection operands +.br +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 \fB -S help\fP where you can find the type name +enclosed in square brackets. Currently, LVM recognizes these field types in +reports: + +.RS +.IP \[bu] 3 +\fBstring\fP 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) +.IP \[bu] 3 +\fBstring list\fP for set of strings +.IP \[bu] 3 +\fBnumber\fP for integer value +.IP \[bu] 3 +\fBsize\fP for integer or floating point number with size unit suffix +(see also \fBlvcreate\fP(8) man page and description for "-L|--size" +option for the list of recognized suffixes) +.IP \[bu] 3 +\fBpercent\fP for floating point number with or without "%" suffix +(e.g. 50 or 50%) +.IP \[bu] 3 +\fBtime\fP for time values +.RE + +When using \fBstring list\fP 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. + +.RS +.IP \[bu] 3 +\fBmatching the set strictly\fP where all items must match - use [ ], e.g. +["a","b","c"] +.IP \[bu] 3 +\fBmatching a subset of the set\fP - use { } with "," or "&&" as item +delimiter, e.g. {"a","b","c"} +.IP \[bu] 3 +\fBmatching an intersection with the set\fP - use { } with "#" or +"||" as item delimiter, e.g. {"a" || "b" || "c"} +.RE + +When using \fBtime\fP 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 \fBEXAMPLES\fP section. + +.RS + +.IP \[bu] 3 +\fBStandard time format\fP + +.RS +.IP - 3 +date +.RS +.IP +YYYY-MM-DD +.IP +YYYY-MM, auto DD=1 +.IP +YYYY, auto MM=01 and DD=01 +.RE + +.IP - 3 +time +.RS +.IP +hh:mm:ss +.IP +hh:mm, auto ss=0 +.IP +hh, auto mm=0, auto ss=0 +.RE + +.IP - 3 +timezone +.RS +.IP ++hh:mm or -hh:mm +.IP ++hh or -hh +.RE + +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: + +.RS +.IP +"2015-07-07 9:51" means range of "2015-07-07 9:51:00" - "2015-07-07 9:51:59". +.IP +"2015-07" means range of "2015-07-01 0:00:00" - "2015-07-31 23:59:59" +.IP +"2015" means range of "2015-01-01 0:00:00" - "2015-12-31 23:59:59" +.RE + +.RE + +.IP \[bu] 3 +\fBAbsolute time format\fP + +Absolute time is defined as number of seconds since the Epoch +(1970:01:01 00:00 +00:00). + +.RS +.IP - 3 + at seconds +.RE + +.IP \[bu] 3 +\fBFreeform time format\fP +.RS +.IP - 3 +weekday names ("Sunday" - "Saturday" or abbreviated as "Sun" - "Sat") +.IP - 3 +labels for points in time ("noon", "midnight") +.IP - 3 +labels for a day relative to current day ("today", "yesterday") +.IP - 3 +points back in time with relative offset from today (N is a number) +.RS +.IP +"N" "seconds" / "minutes" / "hours" / "days" / "weeks" / "years" "ago" +.IP +"N" "secs" / "mins" / "hrs" ... "ago" +.IP +"N" "s" / "m" / "h" ... "ago" +.RE +.IP - 3 +time specification either in hh:mm:ss format or with AM/PM suffixes +.IP - 3 +month names ("January" - "December" or abbreviated as "Jan" - "Dec") +.RE + +.RE + +.B Informal grammar specification +.RS +.IP +.BR STATEMENT " = " column " cmp_op " VALUE " | " \%STATEMENT " log_op " STATEMENT " | " \%(STATEMENT) " | " \%!(STATEMENT) +.IP +.BR VALUE " = " [VALUE " log_op " VALUE] +.br +For list-based types: string list. Matches strictly. +The log_op must always be of one type within the whole list value. +.IP +.BR VALUE " = " {VALUE " log_op " VALUE} +.br +For list-based types: string list. Matches a subset. +The log_op must always be of one type within the whole list value. +.IP +.BR VALUE " = " value +.br +For scalar types: number, size, percent, string (or string regex). +.RE + +.SH EXAMPLES + +.SS Basic usage + +We start our examples with default configuration - \fBlvmconfig\fP(8) is +helpful command to display configuration settings which are currently used, +including all configuration related to reporting. We will use it throughout +examples below to display current configuration. + +.nf +# lvmconfig --type full global/units global/suffix \\ + report/output_format report/compact_output \\ + report/compact_output_cols report/aligned \\ + report/headings report/separator \\ + report/list_item_separator report/prefixes \\ + report/quoted report/columns_as_rows \\ + report/binary_values_as_numeric report/time_format \\ + report/mark_hidden_devices report/two_word_unknown_device \\ + report/buffered +units="h" +suffix=1 +output_format="basic" +compact_output=0 +compact_output_cols="" +aligned=1 +headings=1 +separator=" " +list_item_separator="," +prefixes=0 +quoted=1 +columns_as_rows=0 +binary_values_as_numeric=0 +time_format="%Y-%m-%d %T %z" +mark_hidden_devices=1 +two_word_unknown_device=0 +buffered=1 +.fi + +Also, we start with simple LVM layout with two PVs (/dev/sda, /dev/sdb), +VG (vg) and two LVs (lvol0 and lvol1) in the VG. We display all possible +reports as single commands here, see also \fBpvs\fP(8), \fBvgs\fP(8), +\fBlvs\fP(8) man pages for more information. The field set for each report +type is configured with configuration settings as we already mentioned in +\fBmain report specifics\fP section in this man page. + +.nf +# lvmconfig --type full report/pvs_cols report/pvs_sort \\ + report/pvsegs_cols report/pvsegs_sort report/vgs_cols \\ + report/vgs_sort report/lvs_cols report/lvs_sort \\ + report/segs_cols report/segs_sort +pvs_cols="pv_name,vg_name,pv_fmt,pv_attr,pv_size,pv_free" +pvs_sort="pv_name" +pvsegs_cols="pv_name,vg_name,pv_fmt,pv_attr,pv_size,pv_free, + pvseg_start,pvseg_size" +pvsegs_sort="pv_name,pvseg_start" +vgs_cols="vg_name,pv_count,lv_count,snap_count,vg_attr,vg_size,vg_free" +vgs_sort="vg_name" +lvs_cols="lv_name,vg_name,lv_attr,lv_size,pool_lv,origin,move_pv, + mirror_log,copy_percent,convert_lv" +lvs_sort="vg_name,lv_name" +segs_cols="lv_name,vg_name,lv_attr,stripes,segtype,seg_size" +segs_sort="vg_name,lv_name,seg_start" +.fi + +.nf +# pvs + PV VG Fmt Attr PSize PFree + /dev/sda vg lvm2 a-- 100.00m 88.00m + /dev/sdb vg lvm2 a-- 100.00m 92.00m + +# pvs --segments + PV VG Fmt Attr PSize PFree Start SSize + /dev/sda vg lvm2 a-- 100.00m 88.00m 0 1 + /dev/sda vg lvm2 a-- 100.00m 88.00m 1 1 + /dev/sda vg lvm2 a-- 100.00m 88.00m 2 1 + /dev/sda vg lvm2 a-- 100.00m 88.00m 3 22 + /dev/sdb vg lvm2 a-- 100.00m 92.00m 0 1 + /dev/sdb vg lvm2 a-- 100.00m 92.00m 1 1 + /dev/sdb vg lvm2 a-- 100.00m 92.00m 2 23 + +# vgs + VG #PV #LV #SN Attr VSize VFree + vg 2 2 0 wz--n- 200.00m 180.00m + +# lvs + LV VG Attr LSize Pool Origin Move Log Cpy%Sync Convert + lvol0 vg -wi-a----- 4.00m + lvol1 vg rwi-a-r--- 4.00m 100.00 + +# lvs --segments + LV VG Attr #Str Type SSize + lvol0 vg -wi-a----- 1 linear 4.00m + lvol1 vg rwi-a-r--- 2 raid1 4.00m +.fi + +We will use \fBreport/lvs_cols\fP and \fBreport/lvs_sort\fP configuration +settings to define our own list of fields to use and to sort by that is +different from defaults. You can do this for other reports in same manner +with \fBreport/{pvs,pvseg,vgs,seg}_{cols,sort}\fP configuration settings. +Also note that in the example below, we don't display the "lv_time" field +even though we're using it for sorting - this is allowed. + +.nf +# lvmconfig --type full report/lvs_cols report/lvs_sort +lvs_cols="lv_name,lv_size,origin,pool_lv,copy_percent" +lvs_sort="-lv_time" + +# lvs + LV LSize Origin Pool Cpy%Sync + lvol1 4.00m 100.00 + lvol0 4.00m +.fi + +You can use \fB-o|--options\fP command line option to override current +configuration directly on command line. + +.nf +# lvs -o lv_name,lv_size + LV LSize + lvol1 4.00m + lvol0 4.00m + +# lvs -o+lv_layout + LV LSize Origin Pool Cpy%Sync Layout + lvol1 4.00m 100.00 raid,raid1 + lvol0 4.00m linear + +# lvs -o-origin + LV LSize Pool Cpy%Sync + lvol1 4.00m 100.00 + lvol0 4.00m + +# lvs -o lv_name,lv_size,origin -o+lv_layout -o-origin -O lv_name + LV LSize Layout + lvol0 4.00m linear + lvol1 4.00m raid,raid1 +.fi + +You can obtain the same information with single command where all the +information about PVs, PV segments, LVs and LV segments are obtained +per VG under a single VG lock for consistency, see also \fBlvm fullreport\fP(8) +man page for more information. The fullreport has its own configuration +settings to define field sets to use, similar to individual reports as +displayed above, but configuration settings have "_full" suffix now. +This way, it's possible to configure different sets of fields to display +and to sort by for individual reports as well as the full report. + +.nf +# lvmconfig --type full report/pvs_cols_full \\ + report/pvs_sort_full report/pvsegs_cols_full \\ + report/pvsegs_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 +pvs_cols_full="pv_name,vg_name" +pvs_sort_full="pv_name" +pvsegs_cols_full="pv_name,pvseg_start,pvseg_size" +pvsegs_sort_full="pv_uuid,pvseg_start" +vgs_cols_full="vg_name" +vgs_sort_full="vg_name" +lvs_cols_full="lv_name,vg_name" +lvs_sort_full="vg_name,lv_name" +segs_cols_full="lv_name,seg_start,seg_size" +segs_sort_full="lv_uuid,seg_start" +.fi + +.nf +# lvm fullreport + VG + vg + PV VG + /dev/sda vg + /dev/sdb vg + LV VG + lvol0 vg + lvol1 vg + PV Start SSize + /dev/sda 0 1 + /dev/sda 1 1 + /dev/sda 2 1 + /dev/sda 3 22 + /dev/sdb 0 1 + /dev/sdb 1 1 + /dev/sdb 2 23 + LV Start SSize + lvol0 0 4.00m + lvol1 0 4.00m +.fi + +.SS Automatic output compaction + +If you look at the lvs output above, you can see that the report also contains +fields for which there is no information to display (e.g. the columns under +"Origin" and "Pool" heading - the "origin" and "pool_lv" fields). LVM can +automatically compact report output so such fields are not included in final +output. To enable this feature and to compact all fields, use +\fBreport/compact_output=1\fP in your configuration. + +.nf +# lvmconfig --type full report/compact_output +compact_output=1 + +# lvs + LV LSize Cpy%Sync + lvol1 4.00m 100.00 + lvol0 4.00m + +# lvs vg/lvol0 + LV LSize + lvol0 4.00m +.fi + +Alternatively, you can define which fields should be compacted by configuring +\fBreport/compact_output_cols\fP configuration setting (or \fB-o|--options #\fP +command line option). + +.nf +# lvmconfig --type full report/compact_output report/compact_output_cols +compact_output=0 +compact_output_cols="origin" + +# lvs + LV LSize Pool Cpy%Sync + lvol1 4.00m 100.00 + lvol0 4.00m + +# lvs vg/lvol0 + LV LSize Pool + lvol0 4.00m + +# lvs -o#pool_lv + LV LSize Origin Cpy%Sync + lvol1 4.00m 100.00 + lvol0 4.00m +.fi + +We will use \fBreport/compact_output=1\fP for subsequent examples. + +.SS Further formatting options + +By default, LVM displays sizes in reports in human-readable form which means +that the most suitable unit is used so it's easy to read. You can use +\fBreport/units\fP configuration setting (or \fB--units\fP option directly +on command line) and \fBreport/suffix\fP +configuration setting (or \fB--nosuffix\fP command line option) to change this. + +.nf +# lvs --units b --nosuffix + LV LSize Cpy%Sync + lvol1 4194304 100.00 + lvol0 4194304 +.fi + +If you want to configure whether report headings are displayed or not, use +\fBreport/headings\fP configuration settings (or \fB--noheadings\fP command +line option). + +.nf +# lvs --noheadings + lvol1 4.00m 100.00 + lvol0 4.00m +.fi + +In some cases, it may be useful to display report content as key=value pairs +where key here is actually the field name. Use \fBreport/prefixes\fP +configuration setting (or \fB--nameprefixes\fP command line option) to switch +between standard output and the key=value output. The key=value pair is the +output that is suitable for use in scripts and for other tools to parse easily. +Usually, you also don't want to display headings with the output that has these +key=value pairs. + +.nf +# lvs --noheadings --nameprefixes + LVM2_LV_NAME='lvol1' LVM2_LV_SIZE='4.00m' LVM2_COPY_PERCENT='100.00' + LVM2_LV_NAME='lvol0' LVM2_LV_SIZE='4.00m' LVM2_COPY_PERCENT='' +.fi + +To define whether quotation marks in key=value pairs should be used or not, +use \fBreport/quoted\fP configuration setting (or \fB--unquoted\fP command +line option). + +.nf +# lvs --noheadings --nameprefixes --unquoted + LVM2_LV_NAME=lvol1 LVM2_LV_SIZE=4.00m LVM2_COPY_PERCENT=100.00 + LVM2_LV_NAME=lvol0 LVM2_LV_SIZE=4.00m LVM2_COPY_PERCENT= +.fi + +For easier parsing, you can even transpose the report so each column now +becomes a row in the output. This is done with \fBreport/output_as_rows\fP +configuration setting (or \fB--rows\fP command line option). + +.nf +# lvs --noheadings --nameprefixes --unquoted --rows + LVM2_LV_NAME=lvol1 LVM2_LV_NAME=lvol0 + LVM2_LV_SIZE=4.00m LVM2_LV_SIZE=4.00m + LVM2_COPY_PERCENT=100.00 LVM2_COPY_PERCENT= +.fi + +Use \fBreport/separator\fP configuration setting (or \fB--separator\fP command +line option) to define your own field separator to use. + +.nf +# lvs --noheadings --nameprefixes --unquoted --separator " | " + LVM2_LV_NAME=lvol1 | LVM2_LV_SIZE=4.00m | LVM2_COPY_PERCENT=100.00 + LVM2_LV_NAME=lvol0 | LVM2_LV_SIZE=4.00m | LVM2_COPY_PERCENT= +.fi + +If you are using your own separator, the columns in the output are not aligned +by default. Use \fBreport/aligned\fP configuration setting (or \fB--aligned\fP +command line option) for LVM to add extra spaces in report to align the output +properly. + +.nf +# lvs --separator " | " + LV | LSize | Cpy%Sync + lvol1 | 4.00m | 100.00 + lvol0 | 4.00m | + +# lvs --separator " | " --aligned + LV | LSize | Cpy%Sync + lvol1 | 4.00m | 100.00 + lvol0 | 4.00m | +.fi + +Let's display one one more field in addition ("lv_tags" in this example) +for the lvs report output. + +.nf +# lvs -o+lv_tags + LV LSize Cpy%Sync LV Tags + lvol1 4.00m 100.00 + lvol0 4.00m tagA,tagB +.fi + +The "LV Tags" column in the example above displays two list values, +separated by "," character for LV lvol0. If you need different list item +separator, use \fBreport/list_item_separator\fP configuration setting its +definition. + +.nf +# lvmconfig --type full report/list_item_separator +list_item_separator=";" + +# lvs -o+tags + LV LSize Cpy%Sync LV Tags + lvol1 4.00m 100.00 + lvol0 4.00m tagA;tagB +.fi + +But let's still use the original "," character for list_item_separator +for subsequent examples. + +Format for any of time values displayed in reports can be configured with +\fBreport/time_format\fP configuretion setting. By default complete date +and time is displayed, including timezone. + +.nf +# lvmconfig --type full report/time_format +time_format="%Y-%m-%d %T %z" + +# lvs -o+time + LV LSize Cpy%Sync CTime + lvol1 4.00m 100.00 2016-08-29 12:53:36 +0200 + lvol0 4.00m 2016-08-29 10:15:17 +0200 +.fi + +We can change time format in similar way as we do when using \fBdate\fP(1) +command or \fBstrftime\fP(3) function +(\fBlvmconfig --type default --withcomments report/time_format\fP will +give you complete list of available formatting options). In the example +below, we decided to use %s for number of seconds since Epoch (1970-01-01 UTC). + +.nf +# lvmconfig --type full report/time_format +time_format="%s" + +# lvs + LV Attr LSize Cpy%Sync LV Tags CTime + lvol1 rwi-a-r--- 4.00m 100.00 1472468016 + lvol0 -wi-a----- 4.00m tagA,tagB 1472458517 +.fi + +The \fBlvs\fP does not display hidden LVs by default - to include these LVs +in the output, you need to use \fB-a|--all\fP command line option. Names for +these hidden LVs are displayed within square brackets. + +.nf +# lvs -a + LV LSize Cpy%Sync + lvol1 4.00m 100.00 + [lvol1_rimage_0] 4.00m + [lvol1_rmeta_0] 4.00m + [lvol1_rimage_1] 4.00m + [lvol1_rmeta_1] 4.00m + lvol0 4.00m +.fi + +You can configure LVM to display the square brackets for hidden LVs or not with +\fBreport/mark_hidden_devices\fP configuration setting. + +.nf +# lvmconfig --type full report/mark_hidden_devices +mark_hidden_devices=0 + +# lvs -a + LV LSize Cpy%Sync + lvol1 4.00m 100.00 + lvol1_rimage_0 4.00m + lvol1_rmeta_0 4.00m + lvol1_rimage_1 4.00m + lvol1_rmeta_1 4.00m + lvol0 4.00m +.fi + +It's not recommended to use LV marks for hidden devices to decide whether the +LV is the one to use by end users or not. Please, use "lv_role" field instead +which can report whether the LV is "public" or "private". The private LVs are +used by LVM only and they should not be accessed directly by end users. + +.nf +# lvs -a -o+lv_role + LV LSize Cpy%Sync Role + lvol1 4.00m 100.00 public + lvol1_rimage_0 4.00m private,raid,image + lvol1_rmeta_0 4.00m private,raid,metadata + lvol1_rimage_1 4.00m private,raid,image + lvol1_rmeta_1 4.00m private,raid,metadata + lvol0 4.00m public +.fi + +Some of the reporting fields that LVM reports are of binary nature. For such +fields, it's either possible to display word representation of the value +(this is used by default) or numeric value (0/1 or -1 in case the value is +undefined). + +.nf +# lvs -o+lv_active_locally + LV LSize Cpy%Sync ActLocal + lvol1 4.00m 100.00 active locally + lvol0 4.00m active locally +.fi + +We can change the way how these binary values are displayed with +\fBreport/binary_values_as_numeric\fP configuration setting. + +.nf +# lvmconfig --type full report/binary_values_as_numeric +binary_values_as_numeric=1 + +# lvs -o+lv_active_locally + LV LSize Cpy%Sync ActLocal + lvol1 4.00m 100.00 1 + lvol0 4.00m 1 +.fi + +.SS Changing output format + +LVM can output reports in different formats - use \fBreport/output_format\fP +configuration setting (or \fB--reportformat\fP command line option) to swith +the report output format. Currently, LVM supports \fB"basic"\fP (all the examples +we used above used this format) and \fB"JSON"\fP output format. + +.nf +# lvs -o lv_name,lv_size --reportformat json + { + "report": [ + { + "lv": [ + {"lv_name":"lvol1", "lv_size":"4.00m"}, + {"lv_name":"lvol0", "lv_size":"4.00m"} + ] + } + ] + } +.fi + +Note that some configuration settings and command line options have no +effect with certain report formats. For example, with \fBJSON\fP output, +it doesn't have any meaning to use \fBreport/aligned\fP (\fB--aligned\fP), +\fBreport/noheadings\fP (\fB--noheadings\fP), \fBreport/columns_as_rows\fP +(\fB--rows\fP) or \fBreport/buffered\fP (\fB--unbuffered\fP). All these +configuration settings and command line options are ignored if using the +\fBJSON\fP report output format. + +.SS Selection + +If you need to select only specific rows from report, you can use LVM's +report selection feature. If you call \fB -S help\fP, you'll get +quick help on selection. The help contains list of all fields that LVM +can use in reports together with its type enclosed in square brackets. +The example below contains a line from lvs -S help. + +.nf +# lvs -S help + ... + lv_size - Size of LV in current units. [size] + ... +.fi + +This line tells you you that the "lv_size" field is of "size" type. If you +look at the bottom of the help output, you can see section about +"Selection operators" and its "Comparison operators". + +.nf +# lvs -S help + ... +Selection operators +------------------- +Comparison operators: + =~ - Matching regular expression. [regex] + !~ - Not matching regular expression. [regex] + = - Equal to. [number, size, percent, string, string list, time] + != - Not equal to. [number, size, percent, string, string_list, time] + >= - Greater than or equal to. [number, size, percent, time] + > - Greater than. [number, size, percent, time] + <= - Less than or equal to. [number, size, percent, time] + < - Less than. [number, size, percent, time] +since - Since specified time (same as '>='). [time] +after - After specified time (same as '>'). [time] +until - Until specified time (same as '<='). [time] +before - Before specified time (same as '<'). [time] + ... +.fi + +Here you can match comparison operators that you may use with the "lv_size" +field which is of type "size" - it's =, !=, >=, >, <= and <. You can find +applicable comparison operators for other fields and other field types the +same way. + +To demostrate selection functionality in LVM, we will create more LVs in +addition to lvol0 and lvol1 we used in our previous examples. + +.nf +# lvs -o name,size,origin,snap_percent,tags,time + LV LSize Origin Snap% LV Tags CTime + lvol4 4.00m lvol2 24.61 2016-09-09 16:57:44 +0200 + lvol3 4.00m lvol2 5.08 2016-09-09 16:56:48 +0200 + lvol2 8.00m tagA,tagC,tagD 2016-09-09 16:55:12 +0200 + lvol1 4.00m 2016-08-29 12:53:36 +0200 + lvol0 4.00m tagA,tagB 2016-08-29 10:15:17 +0200 +.fi + +When selecting size and percent fields, we don't need to use units. +For sizes, default "m" (for MiB) is used - this is the same behaviour +as already used for LVM commands when specifying sizes (e.g. lvcreate -L). +For percent fields, "%" is assumed automatically if it's not specified. +The example below also demonstrates how several criteria can be combined +together. + +.nf +# lvs -o name,size,snap_percent -S 'size=8m' + LV LSize + lvol2 8.00m + +# lvs -o name,size,snap_percent -S 'size=8' + LV LSize + lvol2 8.00m + +# lvs -o name,size,snap_percent -S 'size < 5000k' + LV LSize Snap% + lvol4 4.00m 24.61 + lvol3 4.00m 5.08 + lvol1 4.00m + lvol0 4.00m + +# lvs -o name,size,snap_percent -S 'size < 5000k && snap_percent > 20' + LV LSize Snap% + lvol4 4.00m 24.61 + +# lvs -o name,size,snap_percent \\ + -S '(size < 5000k && snap_percent > 20%) || name=lvol2' + LV LSize Snap% + lvol4 4.00m 24.61 + lvol2 8.00m +.fi + +You can also use selection together with processing-oriented commands. + +.nf +# lvchange --addtag test -S 'size < 5000k' + Logical volume vg/lvol1 changed. + Logical volume vg/lvol0 changed. + Logical volume vg/lvol3 changed. + Logical volume vg/lvol4 changed. + +# lvchange --deltag test -S 'tags = test' + Logical volume vg/lvol1 changed. + Logical volume vg/lvol0 changed. + Logical volume vg/lvol3 changed. + Logical volume vg/lvol4 changed. +.fi + +LVM can recognize more complex values used in selection criteria for +string list and time field types. For string lists, you can match +whole list strictly, its subset or intersection. Let's take "lv_tags" +field as an example - we select only rows which contain "tagA" within +tags field. We're using { } to denote that we're interested in subset +that matches. If the subset has only one item, we can leave out { }. + +.nf +# lvs -o name,tags -S 'tags={tagA}' + LV LV Tags + lvol2 tagA,tagC,tagD + lvol0 tagA,tagB + +# lvs -o name,tags -S 'tags=tagA' + LV LV Tags + lvol2 tagA,tagC,tagD + lvol0 tagA,tagB +.fi + +Depending on whether we use "&&" (or ",") or "||" ( or "#") as delimiter +for items in the set we define in selection criterion for string list, +we either match subset ("&&" or ",") or even intersection ("||" or "#"). + +.nf +# lvs -o name,tags -S 'tags={tagA,tagC,tagD}' + LV LV Tags + lvol2 tagA,tagC,tagD + +# lvs -o name,tags -S 'tags={tagA || tagC || tagD}' + LV LV Tags + lvol2 tagA,tagC,tagD + lvol0 tagA,tagB +.fi + +To match the complete set, use [ ] with "&&" (or ",") as delimiter for items. +Also note that the order in which we define items in the set is not relevant. + +.nf +# lvs -o name,tags -S 'tags=[tagA]' + +# lvs -o name,tags -S 'tags=[tagB,tagA]' + LV LV Tags + lvol0 tagA,tagB +.fi + +If you use [ ] with "||" (or "#"), this is exactly the same as using { }. + +.nf +# lvs -o name,tags -S 'tags=[tagA || tagC || tagD]' + LV LV Tags + lvol2 tagA,tagC,tagD + lvol0 tagA,tagB +.fi + +To match a set with no items, use "" to denote this (note that we have +output compaction enabled so the "LV Tags" column is not displayed in +the example below because it's blank and so it gets compacted). + +.nf +# lvs -o name,tags -S 'tags=""' + LV + lvol4 + lvol3 + lvol1 + +# lvs -o name,tags -S 'tags!=""' + LV LV Tags + lvol2 tagA,tagC,tagD + lvol0 tagA,tagB +.fi + +When doing selection based on time fields, we can use either standard, +absolute or freeform time expressions in selection criteria. Examples below +are using standard forms. + +.nf +# lvs -o name,time + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + lvol3 2016-09-09 16:56:48 +0200 + lvol2 2016-09-09 16:55:12 +0200 + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 + +# lvs -o name,time -S 'time since "2016-09-01"' + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + lvol3 2016-09-09 16:56:48 +0200 + lvol2 2016-09-09 16:55:12 +0200 + +# lvs -o name,time -S 'time since "2016-09-09 16:56"' + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + lvol3 2016-09-09 16:56:48 +0200 + +# lvs -o name,time -S 'time since "2016-09-09 16:57:30"' + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + +# lvs -o name,time \\ + -S 'time since "2016-08-29" && time until "2016-09-09 16:55:12"' + LV CTime + lvol2 2016-09-09 16:55:12 +0200 + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 + +# lvs -o name,time \\ + -S 'time since "2016-08-29" && time before "2016-09-09 16:55:12"' + LV CTime + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 +.fi + +Time operators have synonyms: ">=" for since, "<=" for until, +">" for "after" and "<" for "before". + +.nf +# lvs -o name,time \\ + -S 'time >= "2016-08-29" && time <= "2016-09-09 16:55:30"' + LV CTime + lvol2 2016-09-09 16:55:12 +0200 + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 + +# lvs -o name,time \\ + -S 'time since "2016-08-29" && time < "2016-09-09 16:55:12"' + LV CTime + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 +.fi + +Example below demonstrates using absolute time expression. + +.nf +# lvs -o name,time --config report/time_format="%s" + LV CTime + lvol4 1473433064 + lvol3 1473433008 + lvol2 1473432912 + lvol1 1472468016 + lvol0 1472458517 + +# lvs -o name,time -S 'time since @1473433008' + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + lvol3 2016-09-09 16:56:48 +0200 +.fi + +Examples below demonstrates using freeform time expressions. + +.nf +# lvs -o name,time -S 'time since "2 weeks ago"' + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + lvol3 2016-09-09 16:56:48 +0200 + lvol2 2016-09-09 16:55:12 +0200 + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 + +# lvs -o name,time -S 'time since "1 week ago"' + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + lvol3 2016-09-09 16:56:48 +0200 + lvol2 2016-09-09 16:55:12 +0200 + +# lvs -o name,time -S 'time since "2 weeks ago"' + LV CTime + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 + +# lvs -o name,time -S 'time before "1 week ago"' + LV CTime + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 + +# lvs -o name,time -S 'time since "68 hours ago"' + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + lvol3 2016-09-09 16:56:48 +0200 + lvol2 2016-09-09 16:55:12 +0200 + +# lvs -o name,time -S 'time since "1 year 3 months ago"' + LV CTime + lvol4 2016-09-09 16:57:44 +0200 + lvol3 2016-09-09 16:56:48 +0200 + lvol2 2016-09-09 16:55:12 +0200 + lvol1 2016-08-29 12:53:36 +0200 + lvol0 2016-08-29 10:15:17 +0200 +.fi + +.SS Command log reporting + +As described in \fBcategorization based on reporting facility\fP section +at the beginning of this document, both \fBreport-oriented\fP and +\fBprocessing-oriented\fP LVM commands can report the command log if +this is enabled with \fBlog/report_command_log\fP configuration setting. +Just like any other report, we can set the set of fields to display +(\fBlog/command_log_cols\fP) and to sort by (\fBlog/command_log_sort\fP) +for this report. + +.nf +# lvmconfig --type full log/report_command_log log/command_log_cols \\ + log/command_log_sort log/command_log_selection +report_command_log=1 +command_log_cols="log_seq_num,log_type,log_context,log_object_type, + log_object_name,log_object_group,log_message, + log_errno,log_ret_code" +command_log_sort="log_seq_num" +command_log_selection="!(log_type=status && message=success)" + + +# lvs + Logical Volume + ============== + LV LSize Cpy%Sync + lvol1 4.00m 100.00 + lvol0 4.00m + + Command Log + =========== + Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode +.fi + +As you can see, the command log is empty (it contains only field names). +By default, LVM uses selection on the command log report and this case +no row matched the selection criteria, see also \fBlog report specifics\fP +section in this document for more information. We're displaying complete +log report in the example below where we can see that both LVs lvol0 and +lvol1 were successfully processed as well as the VG vg they are part of. + +.nf +# lvmconfig --type full log/command_log_selection +command_log_selection="all" + +# lvs + Logical Volume + ============== + LV LSize Cpy%Sync + lvol1 4.00m 100.00 + lvol0 4.00m + + Command Log + =========== + Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode + 1 status processing lv lvol0 vg success 0 1 + 2 status processing lv lvol1 vg success 0 1 + 3 status processing vg vg success 0 1 + +# lvchange -an vg/lvol1 + Command Log + =========== + Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode + 1 status processing lv lvol1 vg success 0 1 + 2 status processing vg vg success 0 1 +.fi + +.SS Handling multiple reports per single command + +To configure the log report directly on command line, we need to use +\fB--configreport\fP option before we start any \fB-o|--options\fP, +\fB-O|--sort\fP or \fB-S|--select\fP that is targeted for log report. + +.nf +# lvs -o lv_name,lv_size --configreport log -o log_object_type, \\ + log_object_name,log_message,log_ret_code + Logical Volume + ============== + LV LSize + lvol1 4.00m + lvol0 4.00m + + Command Log + =========== + ObjType ObjName Msg RetCode + lv lvol0 success 1 + lv lvol1 success 1 + vg vg success 1 +.fi + +The \fBlvm fullreport\fP, with or without log report, consists of several +reports - the \fB--configreport\fP is also used to target particular +subreport here. + +Below is an extended example with \fBlvm fullreport\fP to illustrate +combination of various options. The report output is in JSON format. +Also, we configure "vg", "pvseg", "seg" and "log" subreport to contain +only specified fields. For the "pvseg" subreport, we're intested only +in PV names having "sda" in their name. For the "log" subreport we're +intested only in log lines related to either "lvol0" object or object +having "sda" in its name. Also, for the log subreport we define ordering +to be based on "log_object_type" field. + +.nf +# lvm fullreport --reportformat json \\ + --configreport vg -o vg_name,vg_size \\ + --configreport pvseg -o pv_name,pvseg_start \\ + -S 'pv_name=~sda' \\ + --configreport seg -o lv_name,seg_start \\ + --configreport log -o log_object_type,log_object_name \\ + -O log_object_type \\ + -S 'log_object_name=lvol0 || \\ + log_object_name=~sda' + { + "report": [ + { + "vg": [ + {"vg_name":"vg", "vg_size":"200.00m"} + ] + , + "pv": [ + {"pv_name":"/dev/sda", "vg_name":"vg"}, + {"pv_name":"/dev/sdb", "vg_name":"vg"} + ] + , + "lv": [ + {"lv_name":"lvol0", "vg_name":"vg"}, + {"lv_name":"lvol1", "vg_name":"vg"} + ] + , + "pvseg": [ + {"pv_name":"/dev/sda", "pvseg_start":"0"}, + {"pv_name":"/dev/sda", "pvseg_start":"1"}, + {"pv_name":"/dev/sda", "pvseg_start":"2"}, + {"pv_name":"/dev/sda", "pvseg_start":"3"} + ] + , + "seg": [ + {"lv_name":"lvol0", "seg_start":"0 "}, + {"lv_name":"lvol1", "seg_start":"0 "} + ] + } + ] + , + "log": [ + {"log_object_type":"lv", "log_object_name":"lvol0"}, + {"log_object_type":"lv", "log_object_name":"lvol0"}, + {"log_object_type":"pv", "log_object_name":"/dev/sda"}, + {"log_object_type":"pv", "log_object_name":"/dev/sda"}, + ] + } +.fi + +.SS Report extensions for LVM shell + +As already stated in \fBlog report coverage\fP paragraph under +\fBlog report specifics\fP in this documentation, when using \fBLVM shell\fP +the \fBlog report\fP coverage is wider. There's also special command +designed to query last command's log report in the \fBLVM shell\fP - +the \fBlastlog\fP command. + +The example below illustrates a situation where we called lvs command. +After that, we inspected the log report with the \fBlastlog\fP, without +any selection so all the log report is displayed on output. Then we called +\fBlastlog\fP further, giving various selection criteria. Then we ran +unknown LVM command "abc" for which the log report displays appropriate +failure state. + +.nf +# lvm +lvm> lvs + Logical Volume + ============== + LV LSize Cpy%Sync + lvol1 4.00m 100.00 + lvol0 4.00m + + Command Log + =========== + Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode + 1 status processing lv lvol0 vg success 0 1 + 2 status processing lv lvol1 vg success 0 1 + 3 status processing vg vg success 0 1 + 4 status shell cmd lvs success 0 1 + +lvm> lastlog + Command Log + =========== + Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode + 1 status processing lv lvol0 vg success 0 1 + 2 status processing lv lvol1 vg success 0 1 + 3 status processing vg vg success 0 1 + 4 status shell cmd lvs success 0 1 + +lvm> lastlog -S log_object_type=lv + Command Log + =========== + Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode + 1 status processing lv lvol0 vg success 0 1 + 2 status processing lv lvol1 vg success 0 1 + +lvm> lastlog -S log_context=shell + Command Log + =========== + Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode + 4 status shell cmd lvs success 0 1 + +lvm> abc + Command Log + =========== + Seq LogType Context ObjType ObjName ObjGrp Msg Errno RetCode + 1 error shell cmd abc No such command 'abc'. Try 'help'. -1 0 + 2 status shell cmd abc failure -1 2 +.fi + +.SH SEE ALSO +\fBlvm\fP (8), +\fBlvmconfig\fP (8), +\fBlvm fullreport\fP (8) diff --git a/man/lvmsadc.8.des b/man/lvmsadc.8.des deleted file mode 100644 index e4cfd8d..0000000 --- a/man/lvmsadc.8.des +++ /dev/null @@ -1,3 +0,0 @@ -lvmsadc is not currently supported in LVM. The device-mapper statistics -facility provides similar performance metrics using the \fBdmstats(8)\fP -command. diff --git a/man/lvmsadc.8_des b/man/lvmsadc.8_des new file mode 100644 index 0000000..e4cfd8d --- /dev/null +++ b/man/lvmsadc.8_des @@ -0,0 +1,3 @@ +lvmsadc is not currently supported in LVM. The device-mapper statistics +facility provides similar performance metrics using the \fBdmstats(8)\fP +command. diff --git a/man/lvmsadc.8_end b/man/lvmsadc.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvmsadc.8_pregen b/man/lvmsadc.8_pregen new file mode 100644 index 0000000..6ee5e3e --- /dev/null +++ b/man/lvmsadc.8_pregen @@ -0,0 +1,280 @@ +.TH LVMSADC 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvmsadc \- Collect activity data +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvmsadc\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +lvmsadc is not currently supported in LVM. The device-mapper statistics +facility provides similar performance metrics using the \fBdmstats(8)\fP +command. + +.P +.SH USAGE +.br +.P +. +\fBlvmsadc\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvmsar.8.des b/man/lvmsar.8.des deleted file mode 100644 index 3177506..0000000 --- a/man/lvmsar.8.des +++ /dev/null @@ -1,3 +0,0 @@ -lvmsar is not currently supported in LVM. The device-mapper statistics -facility provides similar performance metrics using the \fBdmstats(8)\fP -command. diff --git a/man/lvmsar.8_des b/man/lvmsar.8_des new file mode 100644 index 0000000..3177506 --- /dev/null +++ b/man/lvmsar.8_des @@ -0,0 +1,3 @@ +lvmsar is not currently supported in LVM. The device-mapper statistics +facility provides similar performance metrics using the \fBdmstats(8)\fP +command. diff --git a/man/lvmsar.8_end b/man/lvmsar.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvmsar.8_pregen b/man/lvmsar.8_pregen new file mode 100644 index 0000000..f0f57c8 --- /dev/null +++ b/man/lvmsar.8_pregen @@ -0,0 +1,296 @@ +.TH LVMSAR 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvmsar \- Create activity report +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvmsar\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +lvmsar is not currently supported in LVM. The device-mapper statistics +facility provides similar performance metrics using the \fBdmstats(8)\fP +command. + +.P +.SH USAGE +.br +.P +. +\fBlvmsar\fP +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--full\fP ] +.ad b +.br +.ad l +[ \fB-s\fP|\fB--stdin\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--full\fP.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-s\fP|\fB--stdin\fP.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvmsystemid.7.in b/man/lvmsystemid.7.in deleted file mode 100644 index 3aea996..0000000 --- a/man/lvmsystemid.7.in +++ /dev/null @@ -1,354 +0,0 @@ -.TH "LVMSYSTEMID" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" - -.SH NAME -lvmsystemid \(em LVM system ID - -.SH DESCRIPTION - -Local VGs may exist on shared storage where they are visible to multiple -hosts. These VGs are intended to be used by only a single machine, even -though they are visible to many. A system_id identifying a single host -can be assigned to a VG to indicate the VGs owner. The VG owner can use -the VG as usual, and all other hosts will ignore it. This protects the VG -from accidental use by other hosts. - -The system_id is not a dynamic property, and can only be changed in very -limited circumstances (see vgexport and vgimport). Even limited changes -to the VG system_id are not perfectly reflected across hosts. A more -coherent view of shared storage requires using an inter-host locking -system to coordinate access and update caches. - -The system_id is a string uniquely identifying a host. It can be manually -set to a custom value or it can be assigned automatically by lvm using a -unique identifier already available on the host, e.g. machine-id or uname. - -In vgcreate, the local system_id is saved in the new VG metadata. The -local host owns the new VG, and other hosts cannot use it. - -A VG without a system_id can be used by any host, and a VG with a -system_id can only be used by a host with a matching system_id. A -.B foreign VG -is a VG with a system_id as viewed by a host with a system_id -that does not match the VGs system_id. (Or from a host without a -system_id.) - -Valid system_id characters are the same as valid VG name characters. If a -system_id contains invalid characters, those characters are omitted and -remaining characters are used. If a system_id is longer than the maximum -name length, the characters up to the maximum length are used. The -maximum length of a system_id is 128 characters. - -.SS Limitations and warnings - -To benefit fully from system_id, all hosts must have system_id set, and -VGs must have system_id set. A VG on shared storage can be damaged or -destroyed in some cases which the user must be careful to avoid. - -.IP \[bu] 2 -A VG without a system_id can be used without restriction from any host, -even from hosts that have a system_id. Many VGs will not have a system_id -and are unprotected. Verify that a VG has a system_id by running the -command 'vgs -o+systemid' - -A VG will not have a system_id if it was created before this feature was -added to lvm, or if it was created by a host that did not have a system_id -defined. A system_id can be assigned to these VGs by using vgchange ---systemid (see below). - -.IP \[bu] 2 -Two hosts should not be assigned the same system_id. Doing so defeats -the purpose of the system_id which is to distinguish different hosts. - -.IP \[bu] 2 -Orphan PVs (or unused devices) on shared storage are completely -unprotected by the system_id feature. Commands that use these PVs, such -as vgcreate or vgextend, are not prevented from performing conflicting -operations and corrupting the PVs. See the -.B orphans -section for more information. - -.IP \[bu] 2 -A host using an old version of lvm without the system_id feature will not -recognize a new system_id in VGs from other hosts. Even though the old -version of lvm is not blocked from reading a VG with a system_id, it is -blocked from writing to the VG (or its LVs). The new system_id changes -the write mode of a VG, making it appear read-only to previous lvm -versions. - -This also means that if a host downgrades its version of lvm, it would -lose access to any VGs it had created with a system_id. To avoid this, -the system_id should be removed from VGs before downgrading to an lvm -version without the system_id feature. - -.P - -.SS Types of VG access - -A local VG is meant to be used by a single host. -.br -A shared or clustered VG is meant to be used by multiple hosts. -.br -These can be further distinguished as: - -.B Unrestricted: -A local VG that has no system_id. This VG type is unprotected and -accessible to any host. - -.B Owned: -A local VG that has a system_id set, as viewed from the one host with a -matching system_id (the owner). This VG type is by definition acessible. - -.B Foreign: -A local VG that has a system_id set, as viewed from any host with an -unmatching system_id (or no system_id). It is owned by another host. -This VG type is by definition not accessible. - -.B Exported: -A local VG that has been exported with vgexport and has no system_id. -This VG type can only be accessed by vgimport which will change it to -owned. - -.B Shared: -A shared or "lockd" VG has lock_type set and no system_id. -A shared VG is meant to be used on shared storage from multiple hosts, -and is only accessible to hosts using lvmlockd. Applicable only if LVM -is compiled with lockd support. - -.B Clustered: -A clustered or "clvm" VG has the clustered flag set and no system_id. -A clustered VG is meant to be used on shared storage from multiple hosts, -and is only accessible to hosts using clvmd. - -.SS system_id_source - -A host's own system_id can be defined in a number of ways. lvm.conf -global/system_id_source defines the method lvm will use to find the local -system_id: - -.TP -.B none -.br - -lvm will not use a system_id. lvm is allowed to access VGs without a -system_id, and will create new VGs without a system_id. An undefined -system_id_source is equivalent to none. - -.I lvm.conf -.nf -global { - system_id_source = "none" -} -.fi - -.TP -.B machineid -.br - -The content of /etc/machine-id is used as the system_id if available. -See -.BR machine-id (5) -and -.BR systemd-machine-id-setup (1) -to check if machine-id is available on the host. - -.I lvm.conf -.nf -global { - system_id_source = "machineid" -} -.fi - -.TP -.B uname -.br - -The string utsname.nodename from -.BR uname (2) -is used as the system_id. A uname beginning with "localhost" -is ignored and equivalent to none. - -.I lvm.conf -.nf -global { - system_id_source = "uname" -} -.fi - -.TP -.B lvmlocal -.br - -The system_id is defined in lvmlocal.conf local/system_id. - -.I lvm.conf -.nf -global { - system_id_source = "lvmlocal" -} -.fi - -.I lvmlocal.conf -.nf -local { - system_id = "example_name" -} -.fi - -.TP -.B file -.br - -The system_id is defined in a file specified by lvm.conf -global/system_id_file. - -.I lvm.conf -.nf -global { - system_id_source = "file" - system_id_file = "/path/to/file" -} -.fi - -.LP - -Changing system_id_source will often cause the system_id to change, which -may prevent the host from using VGs that it previously used (see -extra_system_ids below to handle this.) - -If a system_id_source other than none fails to resolve a system_id, the -host will be allowed to access VGs with no system_id, but will not be -allowed to access VGs with a defined system_id. - -.SS extra_system_ids - -In some cases, it may be useful for a host to access VGs with different -system_id's, e.g. if a host's system_id changes, and it wants to use VGs -that it created with its old system_id. To allow a host to access VGs -with other system_id's, those other system_id's can be listed in -lvmlocal.conf local/extra_system_ids. - -.I lvmlocal.conf -.nf -local { - extra_system_ids = [ "my_other_name" ] -} -.fi - -.SS vgcreate - -In vgcreate, the host running the command assigns its own system_id to the -new VG. To override this and set another system_id: - -.B vgcreate --systemid -.I SystemID VG Devices - -Overriding the system_id makes it possible for a host to create a VG that -it may not be able to use. Another host with a system_id matching the one -specified may not recognize the new VG without manually rescanning -devices. - -If the --systemid argument is an empty string (""), the VG is created with -no system_id, making it accessible to other hosts (see warnings above.) - -.SS report/display - -The system_id of a VG is displayed with the "systemid" reporting option. - -Report/display commands ignore foreign VGs by default. To report foreign -VGs, the --foreign option can be used. This causes the VGs to be read -from disk. Because lvmetad caching is not used, this option can cause -poor performance. - -.B vgs --foreign -o+systemid - -When a host with no system_id sees foreign VGs, it warns about them as -they are skipped. The host should be assigned a system_id, after which -standard reporting commands will silently ignore foreign VGs. - -.SS vgexport/vgimport - -vgexport clears the system_id. - -Other hosts will continue to see a newly exported VG as foreign because of -local caching (when lvmetad is used). Manually updating the local lvmetad -cache with pvscan --cache will allow a host to recognize the newly -exported VG. - -vgimport sets the VG system_id to the local system_id as determined by -lvm.conf system_id_source. vgimport automatically scans storage for -newly exported VGs. - -After vgimport, the exporting host will continue to see the VG as -exported, and not owned by the new host. Manually updating the local -cache with pvscan --cache will allow a host to recognize the newly -imported VG as foreign. - -.SS vgchange - -A host can change the system_id of its own VGs, but the command requires -confirmation because the host may lose access to the VG being changed: - -.B vgchange --systemid -.I SystemID VG - -The system_id can be removed from a VG by specifying an empty string ("") -as the new system_id. This makes the VG accessible to other hosts (see -warnings above.) - -A host cannot directly change the system_id of a foreign VG. - -To move a VG from one host to another, vgexport and vgimport should be -used. - -To forcibly gain ownership of a foreign VG, a host can add the foreign -system_id to its extra_system_ids list, change the system_id of the -foreign VG to its own, and remove the foreign system_id from its -extra_system_ids list. - -.SS shared VGs - -A shared/lockd VG has no system_id set, allowing multiple hosts to -use it via lvmlockd. Changing a VG to a lockd type will clear the -existing system_id. Applicable only if LVM is compiled with lockd -support. - -.SS clustered VGs - -A clustered/clvm VG has no system_id set, allowing multiple hosts to -use it via clvmd. Changing a VG to clustered will clear the existing -system_id. Changing a VG to not clustered will set the system_id to the -host running the vgchange command. - -.SS creation_host - -In vgcreate, the VG metadata field creation_host is set by default to the -host's uname. The creation_host cannot be changed, and is not used to -control access. When system_id_source is "uname", the system_id and -creation_host will be the same. - -.SS orphans - -Orphan PVs are unused devices; they are not currently used in any VG. -Because of this, they are not protected by a system_id, and any host can -use them. Coordination of changes to orphan PVs is beyond the scope of -system_id. The same is true of any block device that is not a PV. - -The effects of this are especially evident when lvm uses lvmetad caching. -For example, if multiple hosts see an orphan PV, and one host creates a VG -using the orphan, the other hosts will continue to report the PV as an -orphan. Nothing would automatically prevent the other hosts from using -the newly allocated PV and corrupting it. If the other hosts run a -command to rescan devices, and update lvmetad, they would then recognize -that the PV has been used by another host. A command that rescans devices -could be pvscan --cache, or vgs --foreign. - -.SH SEE ALSO -.BR vgcreate (8), -.BR vgchange (8), -.BR vgimport (8), -.BR vgexport (8), -.BR lvm.conf (5), -.BR machine-id (5), -.BR uname (2), -.BR vgs (8) - diff --git a/man/lvmsystemid.7_main b/man/lvmsystemid.7_main new file mode 100644 index 0000000..3aea996 --- /dev/null +++ b/man/lvmsystemid.7_main @@ -0,0 +1,354 @@ +.TH "LVMSYSTEMID" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" + +.SH NAME +lvmsystemid \(em LVM system ID + +.SH DESCRIPTION + +Local VGs may exist on shared storage where they are visible to multiple +hosts. These VGs are intended to be used by only a single machine, even +though they are visible to many. A system_id identifying a single host +can be assigned to a VG to indicate the VGs owner. The VG owner can use +the VG as usual, and all other hosts will ignore it. This protects the VG +from accidental use by other hosts. + +The system_id is not a dynamic property, and can only be changed in very +limited circumstances (see vgexport and vgimport). Even limited changes +to the VG system_id are not perfectly reflected across hosts. A more +coherent view of shared storage requires using an inter-host locking +system to coordinate access and update caches. + +The system_id is a string uniquely identifying a host. It can be manually +set to a custom value or it can be assigned automatically by lvm using a +unique identifier already available on the host, e.g. machine-id or uname. + +In vgcreate, the local system_id is saved in the new VG metadata. The +local host owns the new VG, and other hosts cannot use it. + +A VG without a system_id can be used by any host, and a VG with a +system_id can only be used by a host with a matching system_id. A +.B foreign VG +is a VG with a system_id as viewed by a host with a system_id +that does not match the VGs system_id. (Or from a host without a +system_id.) + +Valid system_id characters are the same as valid VG name characters. If a +system_id contains invalid characters, those characters are omitted and +remaining characters are used. If a system_id is longer than the maximum +name length, the characters up to the maximum length are used. The +maximum length of a system_id is 128 characters. + +.SS Limitations and warnings + +To benefit fully from system_id, all hosts must have system_id set, and +VGs must have system_id set. A VG on shared storage can be damaged or +destroyed in some cases which the user must be careful to avoid. + +.IP \[bu] 2 +A VG without a system_id can be used without restriction from any host, +even from hosts that have a system_id. Many VGs will not have a system_id +and are unprotected. Verify that a VG has a system_id by running the +command 'vgs -o+systemid' + +A VG will not have a system_id if it was created before this feature was +added to lvm, or if it was created by a host that did not have a system_id +defined. A system_id can be assigned to these VGs by using vgchange +--systemid (see below). + +.IP \[bu] 2 +Two hosts should not be assigned the same system_id. Doing so defeats +the purpose of the system_id which is to distinguish different hosts. + +.IP \[bu] 2 +Orphan PVs (or unused devices) on shared storage are completely +unprotected by the system_id feature. Commands that use these PVs, such +as vgcreate or vgextend, are not prevented from performing conflicting +operations and corrupting the PVs. See the +.B orphans +section for more information. + +.IP \[bu] 2 +A host using an old version of lvm without the system_id feature will not +recognize a new system_id in VGs from other hosts. Even though the old +version of lvm is not blocked from reading a VG with a system_id, it is +blocked from writing to the VG (or its LVs). The new system_id changes +the write mode of a VG, making it appear read-only to previous lvm +versions. + +This also means that if a host downgrades its version of lvm, it would +lose access to any VGs it had created with a system_id. To avoid this, +the system_id should be removed from VGs before downgrading to an lvm +version without the system_id feature. + +.P + +.SS Types of VG access + +A local VG is meant to be used by a single host. +.br +A shared or clustered VG is meant to be used by multiple hosts. +.br +These can be further distinguished as: + +.B Unrestricted: +A local VG that has no system_id. This VG type is unprotected and +accessible to any host. + +.B Owned: +A local VG that has a system_id set, as viewed from the one host with a +matching system_id (the owner). This VG type is by definition acessible. + +.B Foreign: +A local VG that has a system_id set, as viewed from any host with an +unmatching system_id (or no system_id). It is owned by another host. +This VG type is by definition not accessible. + +.B Exported: +A local VG that has been exported with vgexport and has no system_id. +This VG type can only be accessed by vgimport which will change it to +owned. + +.B Shared: +A shared or "lockd" VG has lock_type set and no system_id. +A shared VG is meant to be used on shared storage from multiple hosts, +and is only accessible to hosts using lvmlockd. Applicable only if LVM +is compiled with lockd support. + +.B Clustered: +A clustered or "clvm" VG has the clustered flag set and no system_id. +A clustered VG is meant to be used on shared storage from multiple hosts, +and is only accessible to hosts using clvmd. + +.SS system_id_source + +A host's own system_id can be defined in a number of ways. lvm.conf +global/system_id_source defines the method lvm will use to find the local +system_id: + +.TP +.B none +.br + +lvm will not use a system_id. lvm is allowed to access VGs without a +system_id, and will create new VGs without a system_id. An undefined +system_id_source is equivalent to none. + +.I lvm.conf +.nf +global { + system_id_source = "none" +} +.fi + +.TP +.B machineid +.br + +The content of /etc/machine-id is used as the system_id if available. +See +.BR machine-id (5) +and +.BR systemd-machine-id-setup (1) +to check if machine-id is available on the host. + +.I lvm.conf +.nf +global { + system_id_source = "machineid" +} +.fi + +.TP +.B uname +.br + +The string utsname.nodename from +.BR uname (2) +is used as the system_id. A uname beginning with "localhost" +is ignored and equivalent to none. + +.I lvm.conf +.nf +global { + system_id_source = "uname" +} +.fi + +.TP +.B lvmlocal +.br + +The system_id is defined in lvmlocal.conf local/system_id. + +.I lvm.conf +.nf +global { + system_id_source = "lvmlocal" +} +.fi + +.I lvmlocal.conf +.nf +local { + system_id = "example_name" +} +.fi + +.TP +.B file +.br + +The system_id is defined in a file specified by lvm.conf +global/system_id_file. + +.I lvm.conf +.nf +global { + system_id_source = "file" + system_id_file = "/path/to/file" +} +.fi + +.LP + +Changing system_id_source will often cause the system_id to change, which +may prevent the host from using VGs that it previously used (see +extra_system_ids below to handle this.) + +If a system_id_source other than none fails to resolve a system_id, the +host will be allowed to access VGs with no system_id, but will not be +allowed to access VGs with a defined system_id. + +.SS extra_system_ids + +In some cases, it may be useful for a host to access VGs with different +system_id's, e.g. if a host's system_id changes, and it wants to use VGs +that it created with its old system_id. To allow a host to access VGs +with other system_id's, those other system_id's can be listed in +lvmlocal.conf local/extra_system_ids. + +.I lvmlocal.conf +.nf +local { + extra_system_ids = [ "my_other_name" ] +} +.fi + +.SS vgcreate + +In vgcreate, the host running the command assigns its own system_id to the +new VG. To override this and set another system_id: + +.B vgcreate --systemid +.I SystemID VG Devices + +Overriding the system_id makes it possible for a host to create a VG that +it may not be able to use. Another host with a system_id matching the one +specified may not recognize the new VG without manually rescanning +devices. + +If the --systemid argument is an empty string (""), the VG is created with +no system_id, making it accessible to other hosts (see warnings above.) + +.SS report/display + +The system_id of a VG is displayed with the "systemid" reporting option. + +Report/display commands ignore foreign VGs by default. To report foreign +VGs, the --foreign option can be used. This causes the VGs to be read +from disk. Because lvmetad caching is not used, this option can cause +poor performance. + +.B vgs --foreign -o+systemid + +When a host with no system_id sees foreign VGs, it warns about them as +they are skipped. The host should be assigned a system_id, after which +standard reporting commands will silently ignore foreign VGs. + +.SS vgexport/vgimport + +vgexport clears the system_id. + +Other hosts will continue to see a newly exported VG as foreign because of +local caching (when lvmetad is used). Manually updating the local lvmetad +cache with pvscan --cache will allow a host to recognize the newly +exported VG. + +vgimport sets the VG system_id to the local system_id as determined by +lvm.conf system_id_source. vgimport automatically scans storage for +newly exported VGs. + +After vgimport, the exporting host will continue to see the VG as +exported, and not owned by the new host. Manually updating the local +cache with pvscan --cache will allow a host to recognize the newly +imported VG as foreign. + +.SS vgchange + +A host can change the system_id of its own VGs, but the command requires +confirmation because the host may lose access to the VG being changed: + +.B vgchange --systemid +.I SystemID VG + +The system_id can be removed from a VG by specifying an empty string ("") +as the new system_id. This makes the VG accessible to other hosts (see +warnings above.) + +A host cannot directly change the system_id of a foreign VG. + +To move a VG from one host to another, vgexport and vgimport should be +used. + +To forcibly gain ownership of a foreign VG, a host can add the foreign +system_id to its extra_system_ids list, change the system_id of the +foreign VG to its own, and remove the foreign system_id from its +extra_system_ids list. + +.SS shared VGs + +A shared/lockd VG has no system_id set, allowing multiple hosts to +use it via lvmlockd. Changing a VG to a lockd type will clear the +existing system_id. Applicable only if LVM is compiled with lockd +support. + +.SS clustered VGs + +A clustered/clvm VG has no system_id set, allowing multiple hosts to +use it via clvmd. Changing a VG to clustered will clear the existing +system_id. Changing a VG to not clustered will set the system_id to the +host running the vgchange command. + +.SS creation_host + +In vgcreate, the VG metadata field creation_host is set by default to the +host's uname. The creation_host cannot be changed, and is not used to +control access. When system_id_source is "uname", the system_id and +creation_host will be the same. + +.SS orphans + +Orphan PVs are unused devices; they are not currently used in any VG. +Because of this, they are not protected by a system_id, and any host can +use them. Coordination of changes to orphan PVs is beyond the scope of +system_id. The same is true of any block device that is not a PV. + +The effects of this are especially evident when lvm uses lvmetad caching. +For example, if multiple hosts see an orphan PV, and one host creates a VG +using the orphan, the other hosts will continue to report the PV as an +orphan. Nothing would automatically prevent the other hosts from using +the newly allocated PV and corrupting it. If the other hosts run a +command to rescan devices, and update lvmetad, they would then recognize +that the PV has been used by another host. A command that rescans devices +could be pvscan --cache, or vgs --foreign. + +.SH SEE ALSO +.BR vgcreate (8), +.BR vgchange (8), +.BR vgimport (8), +.BR vgexport (8), +.BR lvm.conf (5), +.BR machine-id (5), +.BR uname (2), +.BR vgs (8) + diff --git a/man/lvmthin.7.in b/man/lvmthin.7.in deleted file mode 100644 index f6f8548..0000000 --- a/man/lvmthin.7.in +++ /dev/null @@ -1,1359 +0,0 @@ -.TH "LVMTHIN" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" - -.SH NAME -lvmthin \(em LVM thin provisioning - -.SH DESCRIPTION - -Blocks in a standard logical volume are allocated when the LV is created, -but blocks in a thin provisioned logical volume are allocated as they are -written. Because of this, a thin provisioned LV is given a virtual size, -and can then be much larger than physically available storage. The amount -of physical storage provided for thin provisioned LVs can be increased -later as the need arises. - -Blocks in a standard LV are allocated (during creation) from the VG, but -blocks in a thin LV are allocated (during use) from a special "thin pool -LV". The thin pool LV contains blocks of physical storage, and blocks in -thin LVs just reference blocks in the thin pool LV. - -A thin pool LV must be created before thin LVs can be created within it. -A thin pool LV is created by combining two standard LVs: a large data LV -that will hold blocks for thin LVs, and a metadata LV that will hold -metadata. The metadata tracks which data blocks belong to each thin LV. - -Snapshots of thin LVs are efficient because the data blocks common to a -thin LV and any of its snapshots are shared. Snapshots may be taken of -thin LVs or of other thin snapshots. Blocks common to recursive snapshots -are also shared in the thin pool. There is no limit to or degradation -from sequences of snapshots. - -As thin LVs or snapshot LVs are written to, they consume data blocks in -the thin pool. As free data blocks in the pool decrease, more free blocks -may need to be supplied. This is done by extending the thin pool data LV -with additional physical space from the VG. Removing thin LVs or -snapshots from the thin pool can also free blocks in the thin pool. -However, removing LVs is not always an effective way of freeing space in a -thin pool because the amount is limited to the number of blocks not shared -with other LVs in the pool. - -Incremental block allocation from thin pools can cause thin LVs to become -fragmented. Standard LVs generally avoid this problem by allocating all -the blocks at once during creation. - - -.SH Thin Terms - -.TP -ThinDataLV -.br -thin data LV -.br -large LV created in a VG -.br -used by thin pool to store ThinLV blocks - -.TP -ThinMetaLV -.br -thin metadata LV -.br -small LV created in a VG -.br -used by thin pool to track data block usage - -.TP -ThinPoolLV -.br -thin pool LV -.br -combination of ThinDataLV and ThinMetaLV -.br -contains ThinLVs and SnapLVs - -.TP -ThinLV -.br -thin LV -.br -created from ThinPoolLV -.br -appears blank after creation - -.TP -SnapLV -.br -snapshot LV -.br -created from ThinPoolLV -.br -appears as a snapshot of another LV after creation - - - -.SH Thin Usage - -The primary method for using lvm thin provisioning: - -.SS 1. create ThinDataLV - -Create an LV that will hold thin pool data. - -.B lvcreate \-n ThinDataLV \-L LargeSize VG - -.I Example -.br -# lvcreate \-n pool0 \-L 10G vg - -.SS 2. create ThinMetaLV - -Create an LV that will hold thin pool metadata. - -.B lvcreate \-n ThinMetaLV \-L SmallSize VG - -.I Example -.br -# lvcreate \-n pool0meta \-L 1G vg - -# lvs - LV VG Attr LSize - pool0 vg -wi-a----- 10.00g - pool0meta vg -wi-a----- 1.00g - -.SS 3. create ThinPoolLV - -.nf -Combine the data and metadata LVs into a thin pool LV. -ThinDataLV is renamed to hidden ThinPoolLV_tdata. -ThinMetaLV is renamed to hidden ThinPoolLV_tmeta. -The new ThinPoolLV takes the previous name of ThinDataLV. -.fi - -.B lvconvert \-\-type thin-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV - -.I Example -.br -# lvconvert \-\-type thin-pool \-\-poolmetadata vg/pool0meta vg/pool0 - -# lvs vg/pool0 - LV VG Attr LSize Pool Origin Data% Meta% - pool0 vg twi-a-tz-- 10.00g 0.00 0.00 - -# lvs \-a - LV VG Attr LSize - pool0 vg twi-a-tz-- 10.00g - [pool0_tdata] vg Twi-ao---- 10.00g - [pool0_tmeta] vg ewi-ao---- 1.00g - -.SS 4. create ThinLV - -.nf -Create a new thin LV from the thin pool LV. -The thin LV is created with a virtual size. -Multiple new thin LVs may be created in the thin pool. -Thin LV names must be unique in the VG. -The '--type thin' option is inferred from the virtual size option. -The --thinpool argument specifies which thin pool will -contain the ThinLV. -.fi - -.B lvcreate \-n ThinLV \-V VirtualSize \-\-thinpool ThinPoolLV VG - -.I Example -.br -Create a thin LV in a thin pool: -.br -# lvcreate \-n thin1 \-V 1T \-\-thinpool pool0 vg - -Create another thin LV in the same thin pool: -.br -# lvcreate \-n thin2 \-V 1T \-\-thinpool pool0 vg - -# lvs vg/thin1 vg/thin2 - LV VG Attr LSize Pool Origin Data% - thin1 vg Vwi-a-tz-- 1.00t pool0 0.00 - thin2 vg Vwi-a-tz-- 1.00t pool0 0.00 - -.SS 5. create SnapLV - -Create snapshots of an existing ThinLV or SnapLV. -.br -Do not specify -.BR \-L ", " \-\-size -when creating a thin snapshot. -.br -A size argument will cause an old COW snapshot to be created. - -.B lvcreate \-n SnapLV \-\-snapshot VG/ThinLV -.br -.B lvcreate \-n SnapLV \-\-snapshot VG/PrevSnapLV - -.I Example -.br -Create first snapshot of an existing ThinLV: -.br -# lvcreate \-n thin1s1 \-s vg/thin1 - -Create second snapshot of the same ThinLV: -.br -# lvcreate \-n thin1s2 \-s vg/thin1 - -Create a snapshot of the first snapshot: -.br -# lvcreate \-n thin1s1s1 \-s vg/thin1s1 - -# lvs vg/thin1s1 vg/thin1s2 vg/thin1s1s1 - LV VG Attr LSize Pool Origin - thin1s1 vg Vwi---tz-k 1.00t pool0 thin1 - thin1s2 vg Vwi---tz-k 1.00t pool0 thin1 - thin1s1s1 vg Vwi---tz-k 1.00t pool0 thin1s1 - -.SS 6. activate SnapLV - -Thin snapshots are created with the persistent "activation skip" -flag, indicated by the "k" attribute. Use \-K with lvchange -or vgchange to activate thin snapshots with the "k" attribute. - -.B lvchange \-ay \-K VG/SnapLV - -.I Example -.br -# lvchange \-ay \-K vg/thin1s1 - -# lvs vg/thin1s1 - LV VG Attr LSize Pool Origin - thin1s1 vg Vwi-a-tz-k 1.00t pool0 thin1 - -.SH Thin Topics - -.B Alternate syntax for specifying type thin\-pool -.br -.B Automatic pool metadata LV -.br -.B Specify devices for data and metadata LVs -.br -.B Tolerate device failures using raid -.br -.B Spare metadata LV -.br -.B Metadata check and repair -.br -.B Activation of thin snapshots -.br -.B Removing thin pool LVs, thin LVs and snapshots -.br -.B Manually manage free data space of thin pool LV -.br -.B Manually manage free metadata space of a thin pool LV -.br -.B Using fstrim to increase free space in a thin pool LV -.br -.B Automatically extend thin pool LV -.br -.B Data space exhaustion -.br -.B Metadata space exhaustion -.br -.B Automatic extend settings -.br -.B Zeroing -.br -.B Discard -.br -.B Chunk size -.br -.B Size of pool metadata LV -.br -.B Create a thin snapshot of an external, read only LV -.br -.B Convert a standard LV to a thin LV with an external origin -.br -.B Single step thin pool LV creation -.br -.B Single step thin pool LV and thin LV creation -.br -.B Merge thin snapshots -.br -.B XFS on snapshots - -\& - -.SS Automatic pool metadata LV - -\& - -A thin data LV can be converted to a thin pool LV without specifying a -thin pool metadata LV. LVM automatically creates a metadata LV from the -same VG. - -.B lvcreate \-n ThinDataLV \-L LargeSize VG -.br -.B lvconvert \-\-type thin\-pool VG/ThinDataLV - -.I Example -.br -.nf -# lvcreate \-n pool0 \-L 10G vg -# lvconvert \-\-type thin\-pool vg/pool0 - -# lvs \-a - pool0 vg twi-a-tz-- 10.00g - [pool0_tdata] vg Twi-ao---- 10.00g - [pool0_tmeta] vg ewi-ao---- 16.00m -.fi - - -.SS Specify devices for data and metadata LVs - -\& - -The data and metadata LVs in a thin pool are best created on -separate physical devices. To do that, specify the device name(s) -at the end of the lvcreate line. It can be especially helpful -to use fast devices for the metadata LV. - -.B lvcreate \-n ThinDataLV \-L LargeSize VG LargePV -.br -.B lvcreate \-n ThinMetaLV \-L SmallSize VG SmallPV -.br -.B lvconvert \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV - -.I Example -.br -.nf -# lvcreate \-n pool0 \-L 10G vg /dev/sdA -# lvcreate \-n pool0meta \-L 1G vg /dev/sdB -# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0 -.fi - -.BR lvm.conf (5) -.B thin_pool_metadata_require_separate_pvs -.br -controls the default PV usage for thin pool creation. - -\& - -.SS Tolerate device failures using raid - -\& - -To tolerate device failures, use raid for the pool data LV and -pool metadata LV. This is especially recommended for pool metadata LVs. - -.B lvcreate \-\-type raid1 \-m 1 \-n ThinMetaLV \-L SmallSize VG PVA PVB -.br -.B lvcreate \-\-type raid1 \-m 1 \-n ThinDataLV \-L LargeSize VG PVC PVD -.br -.B lvconvert \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV - -.I Example -.br -.nf -# lvcreate \-\-type raid1 \-m 1 \-n pool0 \-L 10G vg /dev/sdA /dev/sdB -# lvcreate \-\-type raid1 \-m 1 \-n pool0meta \-L 1G vg /dev/sdC /dev/sdD -# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0 -.fi - - -.SS Spare metadata LV - -\& - -The first time a thin pool LV is created, lvm will create a spare -metadata LV in the VG. This behavior can be controlled with the -option \-\-poolmetadataspare y|n. (Future thin pool creations will -also attempt to create the pmspare LV if none exists.) - -To create the pmspare ("pool metadata spare") LV, lvm first creates -an LV with a default name, e.g. lvol0, and then converts this LV to -a hidden LV with the _pmspare suffix, e.g. lvol0_pmspare. - -One pmspare LV is kept in a VG to be used for any thin pool. - -The pmspare LV cannot be created explicitly, but may be removed -explicitly. - -.I Example -.br -.nf -# lvcreate \-n pool0 \-L 10G vg -# lvcreate \-n pool0meta \-L 1G vg -# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0 - -# lvs \-a - [lvol0_pmspare] vg ewi------- - pool0 vg twi---tz-- - [pool0_tdata] vg Twi------- - [pool0_tmeta] vg ewi------- -.fi - -The "Metadata check and repair" section describes the use of -the pmspare LV. - - -.SS Metadata check and repair - -\& - -If thin pool metadata is damaged, it may be repairable. -Checking and repairing thin pool metadata is analagous to -running fsck on a file system. - -When a thin pool LV is activated, lvm runs the thin_check command -to check the correctness of the metadata on the pool metadata LV. - -.BR lvm.conf (5) -.B thin_check_executable -.br -can be set to an empty string ("") to disable the thin_check step. -This is not recommended. - -.BR lvm.conf (5) -.B thin_check_options -.br -controls the command options used for the thin_check command. - -If the thin_check command finds a problem with the metadata, -the thin pool LV is not activated, and the thin pool metadata needs -to be repaired. - -Simple repair commands are not always successful. Advanced repair may -require editing thin pool metadata and lvm metadata. Newer versions of -the kernel and lvm tools may be more successful at repair. Report the -details of damaged thin metadata to get the best advice on recovery. - -Command to repair a thin pool: -.br -.B lvconvert \-\-repair VG/ThinPoolLV - -Repair performs the following steps: - -1. Creates a new, repaired copy of the metadata. -.br -lvconvert runs the thin_repair command to read damaged metadata -from the existing pool metadata LV, and writes a new repaired -copy to the VG's pmspare LV. - -2. Replaces the thin pool metadata LV. -.br -If step 1 is successful, the thin pool metadata LV is replaced -with the pmspare LV containing the corrected metadata. -The previous thin pool metadata LV, containing the damaged metadata, -becomes visible with the new name ThinPoolLV_tmetaN (where N is 0,1,...). - -If the repair works, the thin pool LV and its thin LVs can be activated, -and the LV containing the damaged thin pool metadata can be removed. -It may be useful to move the new metadata LV (previously pmspare) to a -better PV. - -If the repair does not work, the thin pool LV and its thin LVs are lost. - -If metadata is manually restored with thin_repair directly, -the pool metadata LV can be manually swapped with another LV -containing new metadata: - -.B lvconvert \-\-thinpool VG/ThinPoolLV \-\-poolmetadata VG/NewThinMetaLV - - -.SS Activation of thin snapshots - -\& - -When a thin snapshot LV is created, it is by default given the -"activation skip" flag. This flag is indicated by the "k" attribute -displayed by lvs: - -.nf -# lvs vg/thin1s1 - LV VG Attr LSize Pool Origin - thin1s1 vg Vwi---tz-k 1.00t pool0 thin1 -.fi - -This flag causes the snapshot LV to be skipped, i.e. not activated, -by normal activation commands. The skipping behavior does not -apply to deactivation commands. - -A snapshot LV with the "k" attribute can be activated using -the \-K (or \-\-ignoreactivationskip) option in addition to the -standard \-ay (or \-\-activate y) option. - -Command to activate a thin snapshot LV: -.br -.B lvchange \-ay \-K VG/SnapLV - -The persistent "activation skip" flag can be turned off during -lvcreate, or later with lvchange using the \-kn -(or \-\-setactivationskip n) option. -It can be turned on again with \-ky (or \-\-setactivationskip y). - -When the "activation skip" flag is removed, normal activation -commands will activate the LV, and the \-K activation option is -not needed. - -Command to create snapshot LV without the activation skip flag: -.br -.B lvcreate \-kn \-n SnapLV \-s VG/ThinLV - -Command to remove the activation skip flag from a snapshot LV: -.br -.B lvchange \-kn VG/SnapLV - -.BR lvm.conf (5) -.B auto_set_activation_skip -.br -controls the default activation skip setting used by lvcreate. - - -.SS Removing thin pool LVs, thin LVs and snapshots - -\& - -Removing a thin LV and its related snapshots returns the blocks it -used to the thin pool LV. These blocks will be reused for other -thin LVs and snapshots. - -Removing a thin pool LV removes both the data LV and metadata LV -and returns the space to the VG. - -lvremove of thin pool LVs, thin LVs and snapshots cannot be -reversed with vgcfgrestore. - -vgcfgbackup does not back up thin pool metadata. - - -.SS Manually manage free data space of thin pool LV - -\& - -The available free space in a thin pool LV can be displayed -with the lvs command. Free space can be added by extending -the thin pool LV. - -Command to extend thin pool data space: -.br -.B lvextend \-L Size VG/ThinPoolLV - -.I Example -.br -.nf -1. A thin pool LV is using 26.96% of its data blocks. -# lvs - LV VG Attr LSize Pool Origin Data% - pool0 vg twi-a-tz-- 10.00g 26.96 - -2. Double the amount of physical space in the thin pool LV. -# lvextend \-L+10G vg/pool0 - -3. The percentage of used data blocks is half the previous value. -# lvs - LV VG Attr LSize Pool Origin Data% - pool0 vg twi-a-tz-- 20.00g 13.48 -.fi - -Other methods of increasing free data space in a thin pool LV -include removing a thin LV and its related snapsots, or running -fstrim on the file system using a thin LV. - - -.SS Manually manage free metadata space of a thin pool LV - -\& - -The available metadata space in a thin pool LV can be displayed -with the lvs \-o+metadata_percent command. - -Command to extend thin pool metadata space: -.br -.B lvextend \-\-poolmetadatasize Size VG/ThinPoolLV - -.I Example -.br -1. A thin pool LV is using 12.40% of its metadata blocks. -.nf -# lvs \-oname,size,data_percent,metadata_percent vg/pool0 - LV LSize Data% Meta% - pool0 20.00g 13.48 12.40 -.fi - -2. Display a thin pool LV with its component thin data LV and thin metadata LV. -.nf -# lvs \-a \-oname,attr,size vg - LV Attr LSize - pool0 twi-a-tz-- 20.00g - [pool0_tdata] Twi-ao---- 20.00g - [pool0_tmeta] ewi-ao---- 12.00m -.fi - -3. Double the amount of physical space in the thin metadata LV. -.nf -# lvextend \-\-poolmetadatasize +12M vg/pool0 -.fi - -4. The percentage of used metadata blocks is half the previous value. -.nf -# lvs \-a \-oname,size,data_percent,metadata_percent vg - LV LSize Data% Meta% - pool0 20.00g 13.48 6.20 - [pool0_tdata] 20.00g - [pool0_tmeta] 24.00m -.fi - - -.SS Using fstrim to increase free space in a thin pool LV - -\& - -Removing files in a file system on top of a thin LV does not -generally add free space back to the thin pool. Manually running -the fstrim command can return space back to the thin pool that had -been used by removed files. fstrim uses discards and will not work -if the thin pool LV has discards mode set to ignore. - -.I Example -.br -A thin pool has 10G of physical data space, and a thin LV has a virtual -size of 100G. Writing a 1G file to the file system reduces the -free space in the thin pool by 10% and increases the virtual usage -of the file system by 1%. Removing the 1G file restores the virtual -1% to the file system, but does not restore the physical 10% to the -thin pool. The fstrim command restores the physical space to the thin pool. - -.nf -# lvs \-a \-oname,attr,size,pool_lv,origin,data_percent,metadata_percent vg -LV Attr LSize Pool Origin Data% Meta% -pool0 twi-a-tz-- 10.00g 47.01 21.03 -thin1 Vwi-aotz-- 100.00g pool0 2.70 - -# df \-h /mnt/X -Filesystem Size Used Avail Use% Mounted on -/dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X - -# dd if=/dev/zero of=/mnt/X/1Gfile bs=4096 count=262144; sync - -# lvs -pool0 vg twi-a-tz-- 10.00g 57.01 25.26 -thin1 vg Vwi-aotz-- 100.00g pool0 3.70 - -# df \-h /mnt/X -/dev/mapper/vg-thin1 99G 2.1G 92G 3% /mnt/X - -# rm /mnt/X/1Gfile - -# lvs -pool0 vg twi-a-tz-- 10.00g 57.01 25.26 -thin1 vg Vwi-aotz-- 100.00g pool0 3.70 - -# df \-h /mnt/X -/dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X - -# fstrim \-v /mnt/X - -# lvs -pool0 vg twi-a-tz-- 10.00g 47.01 21.03 -thin1 vg Vwi-aotz-- 100.00g pool0 2.70 -.fi - -The "Discard" section covers an option for automatically freeing data -space in a thin pool. - - -.SS Automatically extend thin pool LV - -\& - -The lvm daemon dmeventd (lvm2-monitor) monitors the data usage of thin -pool LVs and extends them when the usage reaches a certain level. The -necessary free space must exist in the VG to extend thin pool LVs. -Monitoring and extension of thin pool LVs are controlled independently. - -.I monitoring - -When a thin pool LV is activated, dmeventd will begin monitoring it by -default. - -Command to start or stop dmeventd monitoring a thin pool LV: -.br -.B lvchange \-\-monitor {y|n} VG/ThinPoolLV - -The current dmeventd monitoring status of a thin pool LV can be displayed -with the command lvs -o+seg_monitor. - -.I autoextend - -dmeventd should be configured to extend thin pool LVs before all data -space is used. Warnings are emitted through syslog when the use of a thin -pool reaches 80%, 85%, 90% and 95%. (See the section "Data space -exhaustion" for the effects of not extending a thin pool LV.) The point -at which dmeventd extends thin pool LVs, and the amount are controlled -with two configuration settings: - -.BR lvm.conf (5) -.B thin_pool_autoextend_threshold -.br -is a percentage full value that defines when the thin pool LV should be -extended. Setting this to 100 disables automatic extention. The minimum -value is 50. - -.BR lvm.conf (5) -.B thin_pool_autoextend_percent -.br -defines how much extra data space should be added to the thin pool LV from -the VG, in percent of its current size. - -.I disabling - -There are multiple ways that extension of thin pools could be prevented: - -.IP \[bu] 2 -If the dmeventd daemon is not running, no monitoring or automatic -extension will occur. - -.IP \[bu] -Even when dmeventd is running, all monitoring can be disabled with the -lvm.conf monitoring setting. - -.IP \[bu] -To activate or create a thin pool LV without interacting with dmeventd, -the --ignoremonitoring option can be used. With this option, the command -will not ask dmeventd to monitor the thin pool LV. - -.IP \[bu] -Setting thin_pool_autoextend_threshould to 100 disables automatic -extension of thin pool LVs, even if they are being monitored by dmeventd. - -.P - -.I Example -.br -If thin_pool_autoextend_threshold is 70 and thin_pool_autoextend_percent is 20, -whenever a pool exceeds 70% usage, it will be extended by another 20%. -For a 1G pool, using 700M will trigger a resize to 1.2G. When the usage exceeds -840M, the pool will be extended to 1.44G, and so on. - - -.SS Data space exhaustion - -\& - -When properly managed, thin pool data space should be extended before it -is all used (see the section "Automatically extend thin pool LV"). If -thin pool data space is already exhausted, it can still be extended (see -the section "Manually manage free data space of thin pool LV".) - -The behavior of a full thin pool is configurable with the --errorwhenfull -y|n option to lvcreate or lvchange. The errorwhenfull setting applies -only to writes; reading thin LVs can continue even when data space is -exhausted. - -Command to change the handling of a full thin pool: -.br -.B lvchange --errorwhenfull {y|n} VG/ThinPoolLV - -.BR lvm.conf (5) -.B error_when_full -.br -controls the default error when full behavior. - -The current setting of a thin pool LV can be displayed with the command: -lvs -o+lv_when_full. - -The errorwhenfull setting does not effect the monitoring and autoextend -settings, and the monitoring/autoextend settings do not effect the -errorwhenfull setting. It is only when monitoring/autoextend are not -effective that the thin pool becomes full and the errorwhenfull setting is -applied. - -.I errorwhenfull n - -This is the default. Writes to thin LVs are accepted and queued, with the -expectation that pool data space will be extended soon. Once data space -is extended, the queued writes will be processed, and the thin pool will -return to normal operation. - -While waiting to be extended, the thin pool will queue writes for up to 60 -seconds (the default). If data space has not been extended after this -time, the queued writes will return an error to the caller, e.g. the file -system. This can result in file system corruption for non-journaled file -systems that may require fsck. When a thin pool returns errors for writes -to a thin LV, any file system is subject to losing unsynced user data. - -The 60 second timeout can be changed or disabled with the dm\-thin\-pool -kernel module option -.B no_space_timeout. -This option sets the number of seconds that thin pools will queue writes. -If set to 0, writes will not time out. Disabling timeouts can result in -the system running out of resources, memory exhaustion, hung tasks, and -deadlocks. (The timeout applies to all thin pools on the system.) - -.I errorwhenfull y - -Writes to thin LVs immediately return an error, and no writes are queued. -In the case of a file system, this can result in corruption that may -require fsck (the specific consequences depend on the thin LV user.) - -.I data percent - -When data space is exhausted, the lvs command displays 100 under Data% for -the thin pool LV: - -.nf -# lvs vg/pool0 - LV VG Attr LSize Pool Origin Data% - pool0 vg twi-a-tz-- 512.00m 100.00 -.fi - -.I causes - -A thin pool may run out of data space for any of the following reasons: - -.IP \[bu] 2 -Automatic extension of the thin pool is disabled, and the thin pool is not -manually extended. (Disabling automatic extension is not recommended.) - -.IP \[bu] -The dmeventd daemon is not running and the thin pool is not manually -extended. (Disabling dmeventd is not recommended.) - -.IP \[bu] -Automatic extension of the thin pool is too slow given the rate of writes -to thin LVs in the pool. (This can be addressed by tuning the -thin_pool_autoextend_threshold and thin_pool_autoextend_percent. -See "Automatic extend settings".) - -.IP \[bu] -The VG does not have enough free blocks to extend the thin pool. - -.P - -.SS Metadata space exhaustion - -\& - -If thin pool metadata space is exhausted (or a thin pool metadata -operation fails), errors will be returned for IO operations on thin LVs. - -When metadata space is exhausted, the lvs command displays 100 under Meta% -for the thin pool LV: - -.nf -# lvs \-o lv_name,size,data_percent,metadata_percent vg/pool0 - LV LSize Data% Meta% - pool0 100.00 -.fi - -The same reasons for thin pool data space exhaustion apply to thin pool -metadata space. - -Metadata space exhaustion can lead to inconsistent thin pool metadata and -inconsistent file systems, so the response requires offline checking and -repair. - -1. Deactivate the thin pool LV, or reboot the system if this is not possible. - -2. Repair thin pool with lvconvert \-\-repair. -.br - See "Metadata check and repair". - -3. Extend pool metadata space with lvextend \-\-poolmetadatasize. -.br - See "Manually manage free metadata space of a thin pool LV". - -4. Check and repair file system with fsck. - - -.SS Automatic extend settings - -\& - -Thin pool LVs can be extended according to preset values. The presets -determine if the LV should be extended based on how full it is, and if so -by how much. When dmeventd monitors thin pool LVs, it uses lvextend with -these presets. (See "Automatically extend thin pool LV".) - -Command to extend a thin pool data LV using presets: -.br -.B lvextend \-\-use\-policies VG/ThinPoolLV - -The command uses these settings: - -.BR lvm.conf (5) -.B thin_pool_autoextend_threshold -.br -autoextend the LV when its usage exceeds this percent. - -.BR lvm.conf (5) -.B thin_pool_autoextend_percent -.br -autoextend the LV by this much additional space. - -To see the default values of these settings, run: - -.B lvmconfig \-\-type default \-\-withcomment -.RS -.B activation/thin_pool_autoextend_threshold -.RE - -.B lvmconfig \-\-type default \-\-withcomment -.RS -.B activation/thin_pool_autoextend_percent -.RE - -To change these values globally, edit -.BR lvm.conf (5). - -To change these values on a per-VG or per-LV basis, attach a "profile" to -the VG or LV. A profile is a collection of config settings, saved in a -local text file (using the lvm.conf format). lvm looks for profiles in -the profile_dir directory, e.g. /etc/lvm/profile/. Once attached to a VG -or LV, lvm will process the VG or LV using the settings from the attached -profile. A profile is named and referenced by its file name. - -To use a profile to customize the lvextend settings for an LV: - -.IP \[bu] 2 -Create a file containing settings, saved in profile_dir. -For the profile_dir location, run: -.br -.B lvmconfig config/profile_dir - -.IP \[bu] 2 -Attach the profile to an LV, using the command: -.br -.B lvchange \-\-metadataprofile ProfileName VG/ThinPoolLV - -.IP \[bu] 2 -Extend the LV using the profile settings: -.br -.B lvextend \-\-use\-policies VG/ThinPoolLV - -.P - -.I Example -.br -.nf -# lvmconfig config/profile_dir -profile_dir="/etc/lvm/profile" - -# cat /etc/lvm/profile/pool0extend.profile -activation { - thin_pool_autoextend_threshold=50 - thin_pool_autoextend_percent=10 -} - -# lvchange --metadataprofile pool0extend vg/pool0 - -# lvextend --use-policies vg/pool0 -.fi - -.I Notes -.IP \[bu] 2 -A profile is attached to a VG or LV by name, where the name references a -local file in profile_dir. If the VG is moved to another machine, the -file with the profile also needs to be moved. - -.IP \[bu] 2 -Only certain settings can be used in a VG or LV profile, see: -.br -.B lvmconfig \-\-type profilable-metadata. - -.IP \[bu] 2 -An LV without a profile of its own will inherit the VG profile. - -.IP \[bu] 2 -Remove a profile from an LV using the command: -.br -.B lvchange --detachprofile VG/ThinPoolLV. - -.IP \[bu] 2 -Commands can also have profiles applied to them. The settings that can be -applied to a command are different than the settings that can be applied -to a VG or LV. See lvmconfig \-\-type profilable\-command. To apply a -profile to a command, write a profile, save it in the profile directory, -and run the command using the option: \-\-commandprofile ProfileName. - - -.SS Zeroing - -\& - -When a thin pool provisions a new data block for a thin LV, the -new block is first overwritten with zeros. The zeroing mode is -indicated by the "z" attribute displayed by lvs. The option \-Z -(or \-\-zero) can be added to commands to specify the zeroing mode. - -Command to set the zeroing mode when creating a thin pool LV: -.br -.B lvconvert \-\-type thin\-pool \-Z{y|n} -.br -.RS -.B \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV -.RE - -Command to change the zeroing mode of an existing thin pool LV: -.br -.B lvchange \-Z{y|n} VG/ThinPoolLV - -If zeroing mode is changed from "n" to "y", previously provisioned -blocks are not zeroed. - -Provisioning of large zeroed chunks impacts performance. - -.BR lvm.conf (5) -.B thin_pool_zero -.br -controls the default zeroing mode used when creating a thin pool. - - -.SS Discard - -\& - -The discard behavior of a thin pool LV determines how discard requests are -handled. Enabling discard under a file system may adversely affect the -file system performance (see the section on fstrim for an alternative.) -Possible discard behaviors: - -ignore: Ignore any discards that are received. - -nopassdown: Process any discards in the thin pool itself and allow -the no longer needed extends to be overwritten by new data. - -passdown: Process discards in the thin pool (as with nopassdown), and -pass the discards down the the underlying device. This is the default -mode. - -Command to display the current discard mode of a thin pool LV: -.br -.B lvs \-o+discards VG/ThinPoolLV - -Command to set the discard mode when creating a thin pool LV: -.br -.B lvconvert \-\-discards {ignore|nopassdown|passdown} -.br -.RS -.B \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV -.RE - -Command to change the discard mode of an existing thin pool LV: -.br -.B lvchange \-\-discards {ignore|nopassdown|passdown} VG/ThinPoolLV - -.I Example -.br -.nf -# lvs \-o name,discards vg/pool0 -pool0 passdown - -# lvchange \-\-discards ignore vg/pool0 -.fi - -.BR lvm.conf (5) -.B thin_pool_discards -.br -controls the default discards mode used when creating a thin pool. - - -.SS Chunk size - -\& - -The size of data blocks managed by a thin pool can be specified with the -\-\-chunksize option when the thin pool LV is created. The default unit -is KiB. The value must be a multiple of 64KiB between 64KiB and 1GiB. - -When a thin pool is used primarily for the thin provisioning feature, a -larger value is optimal. To optimize for many snapshots, a smaller value -reduces copying time and consumes less space. - -Command to display the thin pool LV chunk size: -.br -.B lvs \-o+chunksize VG/ThinPoolLV - -.I Example -.br -.nf -# lvs \-o name,chunksize - pool0 64.00k -.fi - -.BR lvm.conf (5) -.B thin_pool_chunk_size -.br -controls the default chunk size used when creating a thin pool. - -The default value is shown by: -.br -.B lvmconfig \-\-type default allocation/thin_pool_chunk_size - - -.SS Size of pool metadata LV - -\& - -The amount of thin metadata depends on how many blocks are shared between -thin LVs (i.e. through snapshots). A thin pool with many snapshots may -need a larger metadata LV. Thin pool metadata LV sizes can be from 2MiB -to 16GiB. - -When using lvcreate to create what will become a thin metadata LV, the -size is specified with the \-L|\-\-size option. - -When an LVM command automatically creates a thin metadata LV, the size is -specified with the \-\-poolmetadatasize option. When this option is not -given, LVM automatically chooses a size based on the data size and chunk -size. - -It can be hard to predict the amount of metadata space that will be -needed, so it is recommended to start with a size of 1GiB which should be -enough for all practical purposes. A thin pool metadata LV can later be -manually or automatically extended if needed. - - -.SS Create a thin snapshot of an external, read only LV - -\& - -Thin snapshots are typically taken of other thin LVs or other -thin snapshot LVs within the same thin pool. It is also possible -to take thin snapshots of external, read only LVs. Writes to the -snapshot are stored in the thin pool, and the external LV is used -to read unwritten parts of the thin snapshot. - -.B lvcreate \-n SnapLV \-s VG/ExternalOriginLV \-\-thinpool VG/ThinPoolLV - -.I Example -.br -.nf -# lvchange \-an vg/lve -# lvchange \-\-permission r vg/lve -# lvcreate \-n snaplve \-s vg/lve \-\-thinpool vg/pool0 - -# lvs vg/lve vg/snaplve - LV VG Attr LSize Pool Origin Data% - lve vg ori------- 10.00g - snaplve vg Vwi-a-tz-- 10.00g pool0 lve 0.00 -.fi - - -.SS Convert a standard LV to a thin LV with an external origin - -\& - -A new thin LV can be created and given the name of an existing -standard LV. At the same time, the existing LV is converted to a -read only external LV with a new name. Unwritten portions of the -thin LV are read from the external LV. -The new name given to the existing LV can be specified with -\-\-originname, otherwise the existing LV will be given a default -name, e.g. lvol#. - -Convert ExampleLV into a read only external LV with the new name -NewExternalOriginLV, and create a new thin LV that is given the previous -name of ExampleLV. - -.B lvconvert \-\-type thin \-\-thinpool VG/ThinPoolLV -.br -.RS -.B \-\-originname NewExternalOriginLV VG/ExampleLV -.RE - -.I Example -.br -.nf -# lvcreate \-n lv_example \-L 10G vg - -# lvs - lv_example vg -wi-a----- 10.00g - -# lvconvert \-\-type thin \-\-thinpool vg/pool0 - \-\-originname lv_external \-\-thin vg/lv_example - -# lvs - LV VG Attr LSize Pool Origin - lv_example vg Vwi-a-tz-- 10.00g pool0 lv_external - lv_external vg ori------- 10.00g -.fi - - -.SS Single step thin pool LV creation - -\& - -A thin pool LV can be created with a single lvcreate command, -rather than using lvconvert on existing LVs. -This one command creates a thin data LV, a thin metadata LV, -and combines the two into a thin pool LV. - -.B lvcreate \-\-type thin\-pool \-L LargeSize \-n ThinPoolLV VG - -.I Example -.br -.nf -# lvcreate \-\-type thin\-pool \-L8M -n pool0 vg - -# lvs vg/pool0 - LV VG Attr LSize Pool Origin Data% - pool0 vg twi-a-tz-- 8.00m 0.00 - -# lvs \-a - pool0 vg twi-a-tz-- 8.00m - [pool0_tdata] vg Twi-ao---- 8.00m - [pool0_tmeta] vg ewi-ao---- 8.00m -.fi - - -.SS Single step thin pool LV and thin LV creation - -\& - -A thin pool LV and a thin LV can be created with a single -lvcreate command. This one command creates a thin data LV, -a thin metadata LV, combines the two into a thin pool LV, -and creates a thin LV in the new pool. -.br -\-L LargeSize specifies the physical size of the thin pool LV. -.br -\-V VirtualSize specifies the virtual size of the thin LV. - -.B lvcreate \-\-type thin \-V VirtualSize \-L LargeSize -.RS -.B \-n ThinLV \-\-thinpool VG/ThinPoolLV -.RE - -Equivalent to: -.br -.B lvcreate \-\-type thin\-pool \-L LargeSize VG/ThinPoolLV -.br -.B lvcreate \-n ThinLV \-V VirtualSize \-\-thinpool VG/ThinPoolLV - -.I Example -.br -.nf -# lvcreate \-L8M \-V2G \-n thin1 \-\-thinpool vg/pool0 - -# lvs \-a - pool0 vg twi-a-tz-- 8.00m - [pool0_tdata] vg Twi-ao---- 8.00m - [pool0_tmeta] vg ewi-ao---- 8.00m - thin1 vg Vwi-a-tz-- 2.00g pool0 -.fi - - -.SS Merge thin snapshots - -\& - -A thin snapshot can be merged into its origin thin LV using the lvconvert -\-\-merge command. The result of a snapshot merge is that the origin thin -LV takes the content of the snapshot LV, and the snapshot LV is removed. -Any content that was unique to the origin thin LV is lost after the merge. - -Because a merge changes the content of an LV, it cannot be done while the -LVs are open, e.g. mounted. If a merge is initiated while the LVs are open, -the effect of the merge is delayed until the origin thin LV is next -activated. - -.B lvconvert \-\-merge VG/SnapLV - -.I Example -.br -.nf -# lvs vg - LV VG Attr LSize Pool Origin - pool0 vg twi-a-tz-- 10.00g - thin1 vg Vwi-a-tz-- 100.00g pool0 - thin1s1 vg Vwi-a-tz-k 100.00g pool0 thin1 - -# lvconvert \-\-merge vg/thin1s1 - -# lvs vg - LV VG Attr LSize Pool Origin - pool0 vg twi-a-tz-- 10.00g - thin1 vg Vwi-a-tz-- 100.00g pool0 -.fi - -.I Example -.br -.nf -Delayed merging of open LVs. - -# lvs vg - LV VG Attr LSize Pool Origin - pool0 vg twi-a-tz-- 10.00g - thin1 vg Vwi-aotz-- 100.00g pool0 - thin1s1 vg Vwi-aotz-k 100.00g pool0 thin1 - -# df -/dev/mapper/vg-thin1 100G 33M 100G 1% /mnt/X -/dev/mapper/vg-thin1s1 100G 33M 100G 1% /mnt/Xs - -# ls /mnt/X -file1 file2 file3 -# ls /mnt/Xs -file3 file4 file5 - -# lvconvert \-\-merge vg/thin1s1 -Logical volume vg/thin1s1 contains a filesystem in use. -Delaying merge since snapshot is open. -Merging of thin snapshot thin1s1 will occur on next activation. - -# umount /mnt/X -# umount /mnt/Xs - -# lvs \-a vg - LV VG Attr LSize Pool Origin - pool0 vg twi-a-tz-- 10.00g - [pool0_tdata] vg Twi-ao---- 10.00g - [pool0_tmeta] vg ewi-ao---- 1.00g - thin1 vg Owi-a-tz-- 100.00g pool0 - [thin1s1] vg Swi-a-tz-k 100.00g pool0 thin1 - -# lvchange \-an vg/thin1 -# lvchange \-ay vg/thin1 - -# mount /dev/vg/thin1 /mnt/X - -# ls /mnt/X -file3 file4 file5 -.fi - - -.SS XFS on snapshots - -\& - -Mounting an XFS file system on a new snapshot LV requires attention to the -file system's log state and uuid. On the snapshot LV, the xfs log will -contain a dummy transaction, and the xfs uuid will match the uuid from the -file system on the origin LV. - -If the snapshot LV is writable, mounting will recover the log to clear the -dummy transaction, but will require skipping the uuid check: - -mount /dev/VG/SnapLV /mnt \-o nouuid - -Or, the uuid can be changed on disk before mounting: - -xfs_admin \-U generate /dev/VG/SnapLV -.br -mount /dev/VG/SnapLV /mnt - -If the snapshot LV is readonly, the log recovery and uuid check need to be -skipped while mounting readonly: - -mount /dev/VG/SnapLV /mnt \-o ro,nouuid,norecovery - -.SH SEE ALSO -.BR lvm (8), -.BR lvm.conf (5), -.BR lvmconfig (8), -.BR lvcreate (8), -.BR lvconvert (8), -.BR lvchange (8), -.BR lvextend (8), -.BR lvremove (8), -.BR lvs (8), -.BR thin_dump (8), -.BR thin_repair (8) -.BR thin_restore (8) - diff --git a/man/lvmthin.7_main b/man/lvmthin.7_main new file mode 100644 index 0000000..f6f8548 --- /dev/null +++ b/man/lvmthin.7_main @@ -0,0 +1,1359 @@ +.TH "LVMTHIN" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" + +.SH NAME +lvmthin \(em LVM thin provisioning + +.SH DESCRIPTION + +Blocks in a standard logical volume are allocated when the LV is created, +but blocks in a thin provisioned logical volume are allocated as they are +written. Because of this, a thin provisioned LV is given a virtual size, +and can then be much larger than physically available storage. The amount +of physical storage provided for thin provisioned LVs can be increased +later as the need arises. + +Blocks in a standard LV are allocated (during creation) from the VG, but +blocks in a thin LV are allocated (during use) from a special "thin pool +LV". The thin pool LV contains blocks of physical storage, and blocks in +thin LVs just reference blocks in the thin pool LV. + +A thin pool LV must be created before thin LVs can be created within it. +A thin pool LV is created by combining two standard LVs: a large data LV +that will hold blocks for thin LVs, and a metadata LV that will hold +metadata. The metadata tracks which data blocks belong to each thin LV. + +Snapshots of thin LVs are efficient because the data blocks common to a +thin LV and any of its snapshots are shared. Snapshots may be taken of +thin LVs or of other thin snapshots. Blocks common to recursive snapshots +are also shared in the thin pool. There is no limit to or degradation +from sequences of snapshots. + +As thin LVs or snapshot LVs are written to, they consume data blocks in +the thin pool. As free data blocks in the pool decrease, more free blocks +may need to be supplied. This is done by extending the thin pool data LV +with additional physical space from the VG. Removing thin LVs or +snapshots from the thin pool can also free blocks in the thin pool. +However, removing LVs is not always an effective way of freeing space in a +thin pool because the amount is limited to the number of blocks not shared +with other LVs in the pool. + +Incremental block allocation from thin pools can cause thin LVs to become +fragmented. Standard LVs generally avoid this problem by allocating all +the blocks at once during creation. + + +.SH Thin Terms + +.TP +ThinDataLV +.br +thin data LV +.br +large LV created in a VG +.br +used by thin pool to store ThinLV blocks + +.TP +ThinMetaLV +.br +thin metadata LV +.br +small LV created in a VG +.br +used by thin pool to track data block usage + +.TP +ThinPoolLV +.br +thin pool LV +.br +combination of ThinDataLV and ThinMetaLV +.br +contains ThinLVs and SnapLVs + +.TP +ThinLV +.br +thin LV +.br +created from ThinPoolLV +.br +appears blank after creation + +.TP +SnapLV +.br +snapshot LV +.br +created from ThinPoolLV +.br +appears as a snapshot of another LV after creation + + + +.SH Thin Usage + +The primary method for using lvm thin provisioning: + +.SS 1. create ThinDataLV + +Create an LV that will hold thin pool data. + +.B lvcreate \-n ThinDataLV \-L LargeSize VG + +.I Example +.br +# lvcreate \-n pool0 \-L 10G vg + +.SS 2. create ThinMetaLV + +Create an LV that will hold thin pool metadata. + +.B lvcreate \-n ThinMetaLV \-L SmallSize VG + +.I Example +.br +# lvcreate \-n pool0meta \-L 1G vg + +# lvs + LV VG Attr LSize + pool0 vg -wi-a----- 10.00g + pool0meta vg -wi-a----- 1.00g + +.SS 3. create ThinPoolLV + +.nf +Combine the data and metadata LVs into a thin pool LV. +ThinDataLV is renamed to hidden ThinPoolLV_tdata. +ThinMetaLV is renamed to hidden ThinPoolLV_tmeta. +The new ThinPoolLV takes the previous name of ThinDataLV. +.fi + +.B lvconvert \-\-type thin-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV + +.I Example +.br +# lvconvert \-\-type thin-pool \-\-poolmetadata vg/pool0meta vg/pool0 + +# lvs vg/pool0 + LV VG Attr LSize Pool Origin Data% Meta% + pool0 vg twi-a-tz-- 10.00g 0.00 0.00 + +# lvs \-a + LV VG Attr LSize + pool0 vg twi-a-tz-- 10.00g + [pool0_tdata] vg Twi-ao---- 10.00g + [pool0_tmeta] vg ewi-ao---- 1.00g + +.SS 4. create ThinLV + +.nf +Create a new thin LV from the thin pool LV. +The thin LV is created with a virtual size. +Multiple new thin LVs may be created in the thin pool. +Thin LV names must be unique in the VG. +The '--type thin' option is inferred from the virtual size option. +The --thinpool argument specifies which thin pool will +contain the ThinLV. +.fi + +.B lvcreate \-n ThinLV \-V VirtualSize \-\-thinpool ThinPoolLV VG + +.I Example +.br +Create a thin LV in a thin pool: +.br +# lvcreate \-n thin1 \-V 1T \-\-thinpool pool0 vg + +Create another thin LV in the same thin pool: +.br +# lvcreate \-n thin2 \-V 1T \-\-thinpool pool0 vg + +# lvs vg/thin1 vg/thin2 + LV VG Attr LSize Pool Origin Data% + thin1 vg Vwi-a-tz-- 1.00t pool0 0.00 + thin2 vg Vwi-a-tz-- 1.00t pool0 0.00 + +.SS 5. create SnapLV + +Create snapshots of an existing ThinLV or SnapLV. +.br +Do not specify +.BR \-L ", " \-\-size +when creating a thin snapshot. +.br +A size argument will cause an old COW snapshot to be created. + +.B lvcreate \-n SnapLV \-\-snapshot VG/ThinLV +.br +.B lvcreate \-n SnapLV \-\-snapshot VG/PrevSnapLV + +.I Example +.br +Create first snapshot of an existing ThinLV: +.br +# lvcreate \-n thin1s1 \-s vg/thin1 + +Create second snapshot of the same ThinLV: +.br +# lvcreate \-n thin1s2 \-s vg/thin1 + +Create a snapshot of the first snapshot: +.br +# lvcreate \-n thin1s1s1 \-s vg/thin1s1 + +# lvs vg/thin1s1 vg/thin1s2 vg/thin1s1s1 + LV VG Attr LSize Pool Origin + thin1s1 vg Vwi---tz-k 1.00t pool0 thin1 + thin1s2 vg Vwi---tz-k 1.00t pool0 thin1 + thin1s1s1 vg Vwi---tz-k 1.00t pool0 thin1s1 + +.SS 6. activate SnapLV + +Thin snapshots are created with the persistent "activation skip" +flag, indicated by the "k" attribute. Use \-K with lvchange +or vgchange to activate thin snapshots with the "k" attribute. + +.B lvchange \-ay \-K VG/SnapLV + +.I Example +.br +# lvchange \-ay \-K vg/thin1s1 + +# lvs vg/thin1s1 + LV VG Attr LSize Pool Origin + thin1s1 vg Vwi-a-tz-k 1.00t pool0 thin1 + +.SH Thin Topics + +.B Alternate syntax for specifying type thin\-pool +.br +.B Automatic pool metadata LV +.br +.B Specify devices for data and metadata LVs +.br +.B Tolerate device failures using raid +.br +.B Spare metadata LV +.br +.B Metadata check and repair +.br +.B Activation of thin snapshots +.br +.B Removing thin pool LVs, thin LVs and snapshots +.br +.B Manually manage free data space of thin pool LV +.br +.B Manually manage free metadata space of a thin pool LV +.br +.B Using fstrim to increase free space in a thin pool LV +.br +.B Automatically extend thin pool LV +.br +.B Data space exhaustion +.br +.B Metadata space exhaustion +.br +.B Automatic extend settings +.br +.B Zeroing +.br +.B Discard +.br +.B Chunk size +.br +.B Size of pool metadata LV +.br +.B Create a thin snapshot of an external, read only LV +.br +.B Convert a standard LV to a thin LV with an external origin +.br +.B Single step thin pool LV creation +.br +.B Single step thin pool LV and thin LV creation +.br +.B Merge thin snapshots +.br +.B XFS on snapshots + +\& + +.SS Automatic pool metadata LV + +\& + +A thin data LV can be converted to a thin pool LV without specifying a +thin pool metadata LV. LVM automatically creates a metadata LV from the +same VG. + +.B lvcreate \-n ThinDataLV \-L LargeSize VG +.br +.B lvconvert \-\-type thin\-pool VG/ThinDataLV + +.I Example +.br +.nf +# lvcreate \-n pool0 \-L 10G vg +# lvconvert \-\-type thin\-pool vg/pool0 + +# lvs \-a + pool0 vg twi-a-tz-- 10.00g + [pool0_tdata] vg Twi-ao---- 10.00g + [pool0_tmeta] vg ewi-ao---- 16.00m +.fi + + +.SS Specify devices for data and metadata LVs + +\& + +The data and metadata LVs in a thin pool are best created on +separate physical devices. To do that, specify the device name(s) +at the end of the lvcreate line. It can be especially helpful +to use fast devices for the metadata LV. + +.B lvcreate \-n ThinDataLV \-L LargeSize VG LargePV +.br +.B lvcreate \-n ThinMetaLV \-L SmallSize VG SmallPV +.br +.B lvconvert \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV + +.I Example +.br +.nf +# lvcreate \-n pool0 \-L 10G vg /dev/sdA +# lvcreate \-n pool0meta \-L 1G vg /dev/sdB +# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0 +.fi + +.BR lvm.conf (5) +.B thin_pool_metadata_require_separate_pvs +.br +controls the default PV usage for thin pool creation. + +\& + +.SS Tolerate device failures using raid + +\& + +To tolerate device failures, use raid for the pool data LV and +pool metadata LV. This is especially recommended for pool metadata LVs. + +.B lvcreate \-\-type raid1 \-m 1 \-n ThinMetaLV \-L SmallSize VG PVA PVB +.br +.B lvcreate \-\-type raid1 \-m 1 \-n ThinDataLV \-L LargeSize VG PVC PVD +.br +.B lvconvert \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV + +.I Example +.br +.nf +# lvcreate \-\-type raid1 \-m 1 \-n pool0 \-L 10G vg /dev/sdA /dev/sdB +# lvcreate \-\-type raid1 \-m 1 \-n pool0meta \-L 1G vg /dev/sdC /dev/sdD +# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0 +.fi + + +.SS Spare metadata LV + +\& + +The first time a thin pool LV is created, lvm will create a spare +metadata LV in the VG. This behavior can be controlled with the +option \-\-poolmetadataspare y|n. (Future thin pool creations will +also attempt to create the pmspare LV if none exists.) + +To create the pmspare ("pool metadata spare") LV, lvm first creates +an LV with a default name, e.g. lvol0, and then converts this LV to +a hidden LV with the _pmspare suffix, e.g. lvol0_pmspare. + +One pmspare LV is kept in a VG to be used for any thin pool. + +The pmspare LV cannot be created explicitly, but may be removed +explicitly. + +.I Example +.br +.nf +# lvcreate \-n pool0 \-L 10G vg +# lvcreate \-n pool0meta \-L 1G vg +# lvconvert \-\-type thin\-pool \-\-poolmetadata vg/pool0meta vg/pool0 + +# lvs \-a + [lvol0_pmspare] vg ewi------- + pool0 vg twi---tz-- + [pool0_tdata] vg Twi------- + [pool0_tmeta] vg ewi------- +.fi + +The "Metadata check and repair" section describes the use of +the pmspare LV. + + +.SS Metadata check and repair + +\& + +If thin pool metadata is damaged, it may be repairable. +Checking and repairing thin pool metadata is analagous to +running fsck on a file system. + +When a thin pool LV is activated, lvm runs the thin_check command +to check the correctness of the metadata on the pool metadata LV. + +.BR lvm.conf (5) +.B thin_check_executable +.br +can be set to an empty string ("") to disable the thin_check step. +This is not recommended. + +.BR lvm.conf (5) +.B thin_check_options +.br +controls the command options used for the thin_check command. + +If the thin_check command finds a problem with the metadata, +the thin pool LV is not activated, and the thin pool metadata needs +to be repaired. + +Simple repair commands are not always successful. Advanced repair may +require editing thin pool metadata and lvm metadata. Newer versions of +the kernel and lvm tools may be more successful at repair. Report the +details of damaged thin metadata to get the best advice on recovery. + +Command to repair a thin pool: +.br +.B lvconvert \-\-repair VG/ThinPoolLV + +Repair performs the following steps: + +1. Creates a new, repaired copy of the metadata. +.br +lvconvert runs the thin_repair command to read damaged metadata +from the existing pool metadata LV, and writes a new repaired +copy to the VG's pmspare LV. + +2. Replaces the thin pool metadata LV. +.br +If step 1 is successful, the thin pool metadata LV is replaced +with the pmspare LV containing the corrected metadata. +The previous thin pool metadata LV, containing the damaged metadata, +becomes visible with the new name ThinPoolLV_tmetaN (where N is 0,1,...). + +If the repair works, the thin pool LV and its thin LVs can be activated, +and the LV containing the damaged thin pool metadata can be removed. +It may be useful to move the new metadata LV (previously pmspare) to a +better PV. + +If the repair does not work, the thin pool LV and its thin LVs are lost. + +If metadata is manually restored with thin_repair directly, +the pool metadata LV can be manually swapped with another LV +containing new metadata: + +.B lvconvert \-\-thinpool VG/ThinPoolLV \-\-poolmetadata VG/NewThinMetaLV + + +.SS Activation of thin snapshots + +\& + +When a thin snapshot LV is created, it is by default given the +"activation skip" flag. This flag is indicated by the "k" attribute +displayed by lvs: + +.nf +# lvs vg/thin1s1 + LV VG Attr LSize Pool Origin + thin1s1 vg Vwi---tz-k 1.00t pool0 thin1 +.fi + +This flag causes the snapshot LV to be skipped, i.e. not activated, +by normal activation commands. The skipping behavior does not +apply to deactivation commands. + +A snapshot LV with the "k" attribute can be activated using +the \-K (or \-\-ignoreactivationskip) option in addition to the +standard \-ay (or \-\-activate y) option. + +Command to activate a thin snapshot LV: +.br +.B lvchange \-ay \-K VG/SnapLV + +The persistent "activation skip" flag can be turned off during +lvcreate, or later with lvchange using the \-kn +(or \-\-setactivationskip n) option. +It can be turned on again with \-ky (or \-\-setactivationskip y). + +When the "activation skip" flag is removed, normal activation +commands will activate the LV, and the \-K activation option is +not needed. + +Command to create snapshot LV without the activation skip flag: +.br +.B lvcreate \-kn \-n SnapLV \-s VG/ThinLV + +Command to remove the activation skip flag from a snapshot LV: +.br +.B lvchange \-kn VG/SnapLV + +.BR lvm.conf (5) +.B auto_set_activation_skip +.br +controls the default activation skip setting used by lvcreate. + + +.SS Removing thin pool LVs, thin LVs and snapshots + +\& + +Removing a thin LV and its related snapshots returns the blocks it +used to the thin pool LV. These blocks will be reused for other +thin LVs and snapshots. + +Removing a thin pool LV removes both the data LV and metadata LV +and returns the space to the VG. + +lvremove of thin pool LVs, thin LVs and snapshots cannot be +reversed with vgcfgrestore. + +vgcfgbackup does not back up thin pool metadata. + + +.SS Manually manage free data space of thin pool LV + +\& + +The available free space in a thin pool LV can be displayed +with the lvs command. Free space can be added by extending +the thin pool LV. + +Command to extend thin pool data space: +.br +.B lvextend \-L Size VG/ThinPoolLV + +.I Example +.br +.nf +1. A thin pool LV is using 26.96% of its data blocks. +# lvs + LV VG Attr LSize Pool Origin Data% + pool0 vg twi-a-tz-- 10.00g 26.96 + +2. Double the amount of physical space in the thin pool LV. +# lvextend \-L+10G vg/pool0 + +3. The percentage of used data blocks is half the previous value. +# lvs + LV VG Attr LSize Pool Origin Data% + pool0 vg twi-a-tz-- 20.00g 13.48 +.fi + +Other methods of increasing free data space in a thin pool LV +include removing a thin LV and its related snapsots, or running +fstrim on the file system using a thin LV. + + +.SS Manually manage free metadata space of a thin pool LV + +\& + +The available metadata space in a thin pool LV can be displayed +with the lvs \-o+metadata_percent command. + +Command to extend thin pool metadata space: +.br +.B lvextend \-\-poolmetadatasize Size VG/ThinPoolLV + +.I Example +.br +1. A thin pool LV is using 12.40% of its metadata blocks. +.nf +# lvs \-oname,size,data_percent,metadata_percent vg/pool0 + LV LSize Data% Meta% + pool0 20.00g 13.48 12.40 +.fi + +2. Display a thin pool LV with its component thin data LV and thin metadata LV. +.nf +# lvs \-a \-oname,attr,size vg + LV Attr LSize + pool0 twi-a-tz-- 20.00g + [pool0_tdata] Twi-ao---- 20.00g + [pool0_tmeta] ewi-ao---- 12.00m +.fi + +3. Double the amount of physical space in the thin metadata LV. +.nf +# lvextend \-\-poolmetadatasize +12M vg/pool0 +.fi + +4. The percentage of used metadata blocks is half the previous value. +.nf +# lvs \-a \-oname,size,data_percent,metadata_percent vg + LV LSize Data% Meta% + pool0 20.00g 13.48 6.20 + [pool0_tdata] 20.00g + [pool0_tmeta] 24.00m +.fi + + +.SS Using fstrim to increase free space in a thin pool LV + +\& + +Removing files in a file system on top of a thin LV does not +generally add free space back to the thin pool. Manually running +the fstrim command can return space back to the thin pool that had +been used by removed files. fstrim uses discards and will not work +if the thin pool LV has discards mode set to ignore. + +.I Example +.br +A thin pool has 10G of physical data space, and a thin LV has a virtual +size of 100G. Writing a 1G file to the file system reduces the +free space in the thin pool by 10% and increases the virtual usage +of the file system by 1%. Removing the 1G file restores the virtual +1% to the file system, but does not restore the physical 10% to the +thin pool. The fstrim command restores the physical space to the thin pool. + +.nf +# lvs \-a \-oname,attr,size,pool_lv,origin,data_percent,metadata_percent vg +LV Attr LSize Pool Origin Data% Meta% +pool0 twi-a-tz-- 10.00g 47.01 21.03 +thin1 Vwi-aotz-- 100.00g pool0 2.70 + +# df \-h /mnt/X +Filesystem Size Used Avail Use% Mounted on +/dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X + +# dd if=/dev/zero of=/mnt/X/1Gfile bs=4096 count=262144; sync + +# lvs +pool0 vg twi-a-tz-- 10.00g 57.01 25.26 +thin1 vg Vwi-aotz-- 100.00g pool0 3.70 + +# df \-h /mnt/X +/dev/mapper/vg-thin1 99G 2.1G 92G 3% /mnt/X + +# rm /mnt/X/1Gfile + +# lvs +pool0 vg twi-a-tz-- 10.00g 57.01 25.26 +thin1 vg Vwi-aotz-- 100.00g pool0 3.70 + +# df \-h /mnt/X +/dev/mapper/vg-thin1 99G 1.1G 93G 2% /mnt/X + +# fstrim \-v /mnt/X + +# lvs +pool0 vg twi-a-tz-- 10.00g 47.01 21.03 +thin1 vg Vwi-aotz-- 100.00g pool0 2.70 +.fi + +The "Discard" section covers an option for automatically freeing data +space in a thin pool. + + +.SS Automatically extend thin pool LV + +\& + +The lvm daemon dmeventd (lvm2-monitor) monitors the data usage of thin +pool LVs and extends them when the usage reaches a certain level. The +necessary free space must exist in the VG to extend thin pool LVs. +Monitoring and extension of thin pool LVs are controlled independently. + +.I monitoring + +When a thin pool LV is activated, dmeventd will begin monitoring it by +default. + +Command to start or stop dmeventd monitoring a thin pool LV: +.br +.B lvchange \-\-monitor {y|n} VG/ThinPoolLV + +The current dmeventd monitoring status of a thin pool LV can be displayed +with the command lvs -o+seg_monitor. + +.I autoextend + +dmeventd should be configured to extend thin pool LVs before all data +space is used. Warnings are emitted through syslog when the use of a thin +pool reaches 80%, 85%, 90% and 95%. (See the section "Data space +exhaustion" for the effects of not extending a thin pool LV.) The point +at which dmeventd extends thin pool LVs, and the amount are controlled +with two configuration settings: + +.BR lvm.conf (5) +.B thin_pool_autoextend_threshold +.br +is a percentage full value that defines when the thin pool LV should be +extended. Setting this to 100 disables automatic extention. The minimum +value is 50. + +.BR lvm.conf (5) +.B thin_pool_autoextend_percent +.br +defines how much extra data space should be added to the thin pool LV from +the VG, in percent of its current size. + +.I disabling + +There are multiple ways that extension of thin pools could be prevented: + +.IP \[bu] 2 +If the dmeventd daemon is not running, no monitoring or automatic +extension will occur. + +.IP \[bu] +Even when dmeventd is running, all monitoring can be disabled with the +lvm.conf monitoring setting. + +.IP \[bu] +To activate or create a thin pool LV without interacting with dmeventd, +the --ignoremonitoring option can be used. With this option, the command +will not ask dmeventd to monitor the thin pool LV. + +.IP \[bu] +Setting thin_pool_autoextend_threshould to 100 disables automatic +extension of thin pool LVs, even if they are being monitored by dmeventd. + +.P + +.I Example +.br +If thin_pool_autoextend_threshold is 70 and thin_pool_autoextend_percent is 20, +whenever a pool exceeds 70% usage, it will be extended by another 20%. +For a 1G pool, using 700M will trigger a resize to 1.2G. When the usage exceeds +840M, the pool will be extended to 1.44G, and so on. + + +.SS Data space exhaustion + +\& + +When properly managed, thin pool data space should be extended before it +is all used (see the section "Automatically extend thin pool LV"). If +thin pool data space is already exhausted, it can still be extended (see +the section "Manually manage free data space of thin pool LV".) + +The behavior of a full thin pool is configurable with the --errorwhenfull +y|n option to lvcreate or lvchange. The errorwhenfull setting applies +only to writes; reading thin LVs can continue even when data space is +exhausted. + +Command to change the handling of a full thin pool: +.br +.B lvchange --errorwhenfull {y|n} VG/ThinPoolLV + +.BR lvm.conf (5) +.B error_when_full +.br +controls the default error when full behavior. + +The current setting of a thin pool LV can be displayed with the command: +lvs -o+lv_when_full. + +The errorwhenfull setting does not effect the monitoring and autoextend +settings, and the monitoring/autoextend settings do not effect the +errorwhenfull setting. It is only when monitoring/autoextend are not +effective that the thin pool becomes full and the errorwhenfull setting is +applied. + +.I errorwhenfull n + +This is the default. Writes to thin LVs are accepted and queued, with the +expectation that pool data space will be extended soon. Once data space +is extended, the queued writes will be processed, and the thin pool will +return to normal operation. + +While waiting to be extended, the thin pool will queue writes for up to 60 +seconds (the default). If data space has not been extended after this +time, the queued writes will return an error to the caller, e.g. the file +system. This can result in file system corruption for non-journaled file +systems that may require fsck. When a thin pool returns errors for writes +to a thin LV, any file system is subject to losing unsynced user data. + +The 60 second timeout can be changed or disabled with the dm\-thin\-pool +kernel module option +.B no_space_timeout. +This option sets the number of seconds that thin pools will queue writes. +If set to 0, writes will not time out. Disabling timeouts can result in +the system running out of resources, memory exhaustion, hung tasks, and +deadlocks. (The timeout applies to all thin pools on the system.) + +.I errorwhenfull y + +Writes to thin LVs immediately return an error, and no writes are queued. +In the case of a file system, this can result in corruption that may +require fsck (the specific consequences depend on the thin LV user.) + +.I data percent + +When data space is exhausted, the lvs command displays 100 under Data% for +the thin pool LV: + +.nf +# lvs vg/pool0 + LV VG Attr LSize Pool Origin Data% + pool0 vg twi-a-tz-- 512.00m 100.00 +.fi + +.I causes + +A thin pool may run out of data space for any of the following reasons: + +.IP \[bu] 2 +Automatic extension of the thin pool is disabled, and the thin pool is not +manually extended. (Disabling automatic extension is not recommended.) + +.IP \[bu] +The dmeventd daemon is not running and the thin pool is not manually +extended. (Disabling dmeventd is not recommended.) + +.IP \[bu] +Automatic extension of the thin pool is too slow given the rate of writes +to thin LVs in the pool. (This can be addressed by tuning the +thin_pool_autoextend_threshold and thin_pool_autoextend_percent. +See "Automatic extend settings".) + +.IP \[bu] +The VG does not have enough free blocks to extend the thin pool. + +.P + +.SS Metadata space exhaustion + +\& + +If thin pool metadata space is exhausted (or a thin pool metadata +operation fails), errors will be returned for IO operations on thin LVs. + +When metadata space is exhausted, the lvs command displays 100 under Meta% +for the thin pool LV: + +.nf +# lvs \-o lv_name,size,data_percent,metadata_percent vg/pool0 + LV LSize Data% Meta% + pool0 100.00 +.fi + +The same reasons for thin pool data space exhaustion apply to thin pool +metadata space. + +Metadata space exhaustion can lead to inconsistent thin pool metadata and +inconsistent file systems, so the response requires offline checking and +repair. + +1. Deactivate the thin pool LV, or reboot the system if this is not possible. + +2. Repair thin pool with lvconvert \-\-repair. +.br + See "Metadata check and repair". + +3. Extend pool metadata space with lvextend \-\-poolmetadatasize. +.br + See "Manually manage free metadata space of a thin pool LV". + +4. Check and repair file system with fsck. + + +.SS Automatic extend settings + +\& + +Thin pool LVs can be extended according to preset values. The presets +determine if the LV should be extended based on how full it is, and if so +by how much. When dmeventd monitors thin pool LVs, it uses lvextend with +these presets. (See "Automatically extend thin pool LV".) + +Command to extend a thin pool data LV using presets: +.br +.B lvextend \-\-use\-policies VG/ThinPoolLV + +The command uses these settings: + +.BR lvm.conf (5) +.B thin_pool_autoextend_threshold +.br +autoextend the LV when its usage exceeds this percent. + +.BR lvm.conf (5) +.B thin_pool_autoextend_percent +.br +autoextend the LV by this much additional space. + +To see the default values of these settings, run: + +.B lvmconfig \-\-type default \-\-withcomment +.RS +.B activation/thin_pool_autoextend_threshold +.RE + +.B lvmconfig \-\-type default \-\-withcomment +.RS +.B activation/thin_pool_autoextend_percent +.RE + +To change these values globally, edit +.BR lvm.conf (5). + +To change these values on a per-VG or per-LV basis, attach a "profile" to +the VG or LV. A profile is a collection of config settings, saved in a +local text file (using the lvm.conf format). lvm looks for profiles in +the profile_dir directory, e.g. /etc/lvm/profile/. Once attached to a VG +or LV, lvm will process the VG or LV using the settings from the attached +profile. A profile is named and referenced by its file name. + +To use a profile to customize the lvextend settings for an LV: + +.IP \[bu] 2 +Create a file containing settings, saved in profile_dir. +For the profile_dir location, run: +.br +.B lvmconfig config/profile_dir + +.IP \[bu] 2 +Attach the profile to an LV, using the command: +.br +.B lvchange \-\-metadataprofile ProfileName VG/ThinPoolLV + +.IP \[bu] 2 +Extend the LV using the profile settings: +.br +.B lvextend \-\-use\-policies VG/ThinPoolLV + +.P + +.I Example +.br +.nf +# lvmconfig config/profile_dir +profile_dir="/etc/lvm/profile" + +# cat /etc/lvm/profile/pool0extend.profile +activation { + thin_pool_autoextend_threshold=50 + thin_pool_autoextend_percent=10 +} + +# lvchange --metadataprofile pool0extend vg/pool0 + +# lvextend --use-policies vg/pool0 +.fi + +.I Notes +.IP \[bu] 2 +A profile is attached to a VG or LV by name, where the name references a +local file in profile_dir. If the VG is moved to another machine, the +file with the profile also needs to be moved. + +.IP \[bu] 2 +Only certain settings can be used in a VG or LV profile, see: +.br +.B lvmconfig \-\-type profilable-metadata. + +.IP \[bu] 2 +An LV without a profile of its own will inherit the VG profile. + +.IP \[bu] 2 +Remove a profile from an LV using the command: +.br +.B lvchange --detachprofile VG/ThinPoolLV. + +.IP \[bu] 2 +Commands can also have profiles applied to them. The settings that can be +applied to a command are different than the settings that can be applied +to a VG or LV. See lvmconfig \-\-type profilable\-command. To apply a +profile to a command, write a profile, save it in the profile directory, +and run the command using the option: \-\-commandprofile ProfileName. + + +.SS Zeroing + +\& + +When a thin pool provisions a new data block for a thin LV, the +new block is first overwritten with zeros. The zeroing mode is +indicated by the "z" attribute displayed by lvs. The option \-Z +(or \-\-zero) can be added to commands to specify the zeroing mode. + +Command to set the zeroing mode when creating a thin pool LV: +.br +.B lvconvert \-\-type thin\-pool \-Z{y|n} +.br +.RS +.B \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV +.RE + +Command to change the zeroing mode of an existing thin pool LV: +.br +.B lvchange \-Z{y|n} VG/ThinPoolLV + +If zeroing mode is changed from "n" to "y", previously provisioned +blocks are not zeroed. + +Provisioning of large zeroed chunks impacts performance. + +.BR lvm.conf (5) +.B thin_pool_zero +.br +controls the default zeroing mode used when creating a thin pool. + + +.SS Discard + +\& + +The discard behavior of a thin pool LV determines how discard requests are +handled. Enabling discard under a file system may adversely affect the +file system performance (see the section on fstrim for an alternative.) +Possible discard behaviors: + +ignore: Ignore any discards that are received. + +nopassdown: Process any discards in the thin pool itself and allow +the no longer needed extends to be overwritten by new data. + +passdown: Process discards in the thin pool (as with nopassdown), and +pass the discards down the the underlying device. This is the default +mode. + +Command to display the current discard mode of a thin pool LV: +.br +.B lvs \-o+discards VG/ThinPoolLV + +Command to set the discard mode when creating a thin pool LV: +.br +.B lvconvert \-\-discards {ignore|nopassdown|passdown} +.br +.RS +.B \-\-type thin\-pool \-\-poolmetadata VG/ThinMetaLV VG/ThinDataLV +.RE + +Command to change the discard mode of an existing thin pool LV: +.br +.B lvchange \-\-discards {ignore|nopassdown|passdown} VG/ThinPoolLV + +.I Example +.br +.nf +# lvs \-o name,discards vg/pool0 +pool0 passdown + +# lvchange \-\-discards ignore vg/pool0 +.fi + +.BR lvm.conf (5) +.B thin_pool_discards +.br +controls the default discards mode used when creating a thin pool. + + +.SS Chunk size + +\& + +The size of data blocks managed by a thin pool can be specified with the +\-\-chunksize option when the thin pool LV is created. The default unit +is KiB. The value must be a multiple of 64KiB between 64KiB and 1GiB. + +When a thin pool is used primarily for the thin provisioning feature, a +larger value is optimal. To optimize for many snapshots, a smaller value +reduces copying time and consumes less space. + +Command to display the thin pool LV chunk size: +.br +.B lvs \-o+chunksize VG/ThinPoolLV + +.I Example +.br +.nf +# lvs \-o name,chunksize + pool0 64.00k +.fi + +.BR lvm.conf (5) +.B thin_pool_chunk_size +.br +controls the default chunk size used when creating a thin pool. + +The default value is shown by: +.br +.B lvmconfig \-\-type default allocation/thin_pool_chunk_size + + +.SS Size of pool metadata LV + +\& + +The amount of thin metadata depends on how many blocks are shared between +thin LVs (i.e. through snapshots). A thin pool with many snapshots may +need a larger metadata LV. Thin pool metadata LV sizes can be from 2MiB +to 16GiB. + +When using lvcreate to create what will become a thin metadata LV, the +size is specified with the \-L|\-\-size option. + +When an LVM command automatically creates a thin metadata LV, the size is +specified with the \-\-poolmetadatasize option. When this option is not +given, LVM automatically chooses a size based on the data size and chunk +size. + +It can be hard to predict the amount of metadata space that will be +needed, so it is recommended to start with a size of 1GiB which should be +enough for all practical purposes. A thin pool metadata LV can later be +manually or automatically extended if needed. + + +.SS Create a thin snapshot of an external, read only LV + +\& + +Thin snapshots are typically taken of other thin LVs or other +thin snapshot LVs within the same thin pool. It is also possible +to take thin snapshots of external, read only LVs. Writes to the +snapshot are stored in the thin pool, and the external LV is used +to read unwritten parts of the thin snapshot. + +.B lvcreate \-n SnapLV \-s VG/ExternalOriginLV \-\-thinpool VG/ThinPoolLV + +.I Example +.br +.nf +# lvchange \-an vg/lve +# lvchange \-\-permission r vg/lve +# lvcreate \-n snaplve \-s vg/lve \-\-thinpool vg/pool0 + +# lvs vg/lve vg/snaplve + LV VG Attr LSize Pool Origin Data% + lve vg ori------- 10.00g + snaplve vg Vwi-a-tz-- 10.00g pool0 lve 0.00 +.fi + + +.SS Convert a standard LV to a thin LV with an external origin + +\& + +A new thin LV can be created and given the name of an existing +standard LV. At the same time, the existing LV is converted to a +read only external LV with a new name. Unwritten portions of the +thin LV are read from the external LV. +The new name given to the existing LV can be specified with +\-\-originname, otherwise the existing LV will be given a default +name, e.g. lvol#. + +Convert ExampleLV into a read only external LV with the new name +NewExternalOriginLV, and create a new thin LV that is given the previous +name of ExampleLV. + +.B lvconvert \-\-type thin \-\-thinpool VG/ThinPoolLV +.br +.RS +.B \-\-originname NewExternalOriginLV VG/ExampleLV +.RE + +.I Example +.br +.nf +# lvcreate \-n lv_example \-L 10G vg + +# lvs + lv_example vg -wi-a----- 10.00g + +# lvconvert \-\-type thin \-\-thinpool vg/pool0 + \-\-originname lv_external \-\-thin vg/lv_example + +# lvs + LV VG Attr LSize Pool Origin + lv_example vg Vwi-a-tz-- 10.00g pool0 lv_external + lv_external vg ori------- 10.00g +.fi + + +.SS Single step thin pool LV creation + +\& + +A thin pool LV can be created with a single lvcreate command, +rather than using lvconvert on existing LVs. +This one command creates a thin data LV, a thin metadata LV, +and combines the two into a thin pool LV. + +.B lvcreate \-\-type thin\-pool \-L LargeSize \-n ThinPoolLV VG + +.I Example +.br +.nf +# lvcreate \-\-type thin\-pool \-L8M -n pool0 vg + +# lvs vg/pool0 + LV VG Attr LSize Pool Origin Data% + pool0 vg twi-a-tz-- 8.00m 0.00 + +# lvs \-a + pool0 vg twi-a-tz-- 8.00m + [pool0_tdata] vg Twi-ao---- 8.00m + [pool0_tmeta] vg ewi-ao---- 8.00m +.fi + + +.SS Single step thin pool LV and thin LV creation + +\& + +A thin pool LV and a thin LV can be created with a single +lvcreate command. This one command creates a thin data LV, +a thin metadata LV, combines the two into a thin pool LV, +and creates a thin LV in the new pool. +.br +\-L LargeSize specifies the physical size of the thin pool LV. +.br +\-V VirtualSize specifies the virtual size of the thin LV. + +.B lvcreate \-\-type thin \-V VirtualSize \-L LargeSize +.RS +.B \-n ThinLV \-\-thinpool VG/ThinPoolLV +.RE + +Equivalent to: +.br +.B lvcreate \-\-type thin\-pool \-L LargeSize VG/ThinPoolLV +.br +.B lvcreate \-n ThinLV \-V VirtualSize \-\-thinpool VG/ThinPoolLV + +.I Example +.br +.nf +# lvcreate \-L8M \-V2G \-n thin1 \-\-thinpool vg/pool0 + +# lvs \-a + pool0 vg twi-a-tz-- 8.00m + [pool0_tdata] vg Twi-ao---- 8.00m + [pool0_tmeta] vg ewi-ao---- 8.00m + thin1 vg Vwi-a-tz-- 2.00g pool0 +.fi + + +.SS Merge thin snapshots + +\& + +A thin snapshot can be merged into its origin thin LV using the lvconvert +\-\-merge command. The result of a snapshot merge is that the origin thin +LV takes the content of the snapshot LV, and the snapshot LV is removed. +Any content that was unique to the origin thin LV is lost after the merge. + +Because a merge changes the content of an LV, it cannot be done while the +LVs are open, e.g. mounted. If a merge is initiated while the LVs are open, +the effect of the merge is delayed until the origin thin LV is next +activated. + +.B lvconvert \-\-merge VG/SnapLV + +.I Example +.br +.nf +# lvs vg + LV VG Attr LSize Pool Origin + pool0 vg twi-a-tz-- 10.00g + thin1 vg Vwi-a-tz-- 100.00g pool0 + thin1s1 vg Vwi-a-tz-k 100.00g pool0 thin1 + +# lvconvert \-\-merge vg/thin1s1 + +# lvs vg + LV VG Attr LSize Pool Origin + pool0 vg twi-a-tz-- 10.00g + thin1 vg Vwi-a-tz-- 100.00g pool0 +.fi + +.I Example +.br +.nf +Delayed merging of open LVs. + +# lvs vg + LV VG Attr LSize Pool Origin + pool0 vg twi-a-tz-- 10.00g + thin1 vg Vwi-aotz-- 100.00g pool0 + thin1s1 vg Vwi-aotz-k 100.00g pool0 thin1 + +# df +/dev/mapper/vg-thin1 100G 33M 100G 1% /mnt/X +/dev/mapper/vg-thin1s1 100G 33M 100G 1% /mnt/Xs + +# ls /mnt/X +file1 file2 file3 +# ls /mnt/Xs +file3 file4 file5 + +# lvconvert \-\-merge vg/thin1s1 +Logical volume vg/thin1s1 contains a filesystem in use. +Delaying merge since snapshot is open. +Merging of thin snapshot thin1s1 will occur on next activation. + +# umount /mnt/X +# umount /mnt/Xs + +# lvs \-a vg + LV VG Attr LSize Pool Origin + pool0 vg twi-a-tz-- 10.00g + [pool0_tdata] vg Twi-ao---- 10.00g + [pool0_tmeta] vg ewi-ao---- 1.00g + thin1 vg Owi-a-tz-- 100.00g pool0 + [thin1s1] vg Swi-a-tz-k 100.00g pool0 thin1 + +# lvchange \-an vg/thin1 +# lvchange \-ay vg/thin1 + +# mount /dev/vg/thin1 /mnt/X + +# ls /mnt/X +file3 file4 file5 +.fi + + +.SS XFS on snapshots + +\& + +Mounting an XFS file system on a new snapshot LV requires attention to the +file system's log state and uuid. On the snapshot LV, the xfs log will +contain a dummy transaction, and the xfs uuid will match the uuid from the +file system on the origin LV. + +If the snapshot LV is writable, mounting will recover the log to clear the +dummy transaction, but will require skipping the uuid check: + +mount /dev/VG/SnapLV /mnt \-o nouuid + +Or, the uuid can be changed on disk before mounting: + +xfs_admin \-U generate /dev/VG/SnapLV +.br +mount /dev/VG/SnapLV /mnt + +If the snapshot LV is readonly, the log recovery and uuid check need to be +skipped while mounting readonly: + +mount /dev/VG/SnapLV /mnt \-o ro,nouuid,norecovery + +.SH SEE ALSO +.BR lvm (8), +.BR lvm.conf (5), +.BR lvmconfig (8), +.BR lvcreate (8), +.BR lvconvert (8), +.BR lvchange (8), +.BR lvextend (8), +.BR lvremove (8), +.BR lvs (8), +.BR thin_dump (8), +.BR thin_repair (8) +.BR thin_restore (8) + diff --git a/man/lvreduce.8.des b/man/lvreduce.8.des deleted file mode 100644 index 3d5fc2a..0000000 --- a/man/lvreduce.8.des +++ /dev/null @@ -1,19 +0,0 @@ -lvreduce reduces the size of an LV. The freed logical extents are returned -to the VG to be used by other LVs. A copy\-on\-write snapshot LV can also -be reduced if less space is needed to hold COW blocks. Use -\fBlvconvert\fP(8) to change the number of data images in a RAID or -mirrored LV. - -Be careful when reducing an LV's size, because data in the reduced area is -lost. Ensure that any file system on the LV is resized \fBbefore\fP -running lvreduce so that the removed extents are not in use by the file -system. - -Sizes will be rounded if necessary. For example, the LV size must be an -exact number of extents, and the size of a striped segment must be a -multiple of the number of stripes. - -In the usage section below, \fB--size\fP \fISize\fP can be replaced -with \fB--extents\fP \fINumber\fP. See both descriptions -the options section. - diff --git a/man/lvreduce.8.end b/man/lvreduce.8.end deleted file mode 100644 index 59fde52..0000000 --- a/man/lvreduce.8.end +++ /dev/null @@ -1,5 +0,0 @@ -.SH EXAMPLES - -Reduce the size of an LV by 3 logical extents: -.br -.B lvreduce \-l \-3 vg00/lvol1 diff --git a/man/lvreduce.8_des b/man/lvreduce.8_des new file mode 100644 index 0000000..3d5fc2a --- /dev/null +++ b/man/lvreduce.8_des @@ -0,0 +1,19 @@ +lvreduce reduces the size of an LV. The freed logical extents are returned +to the VG to be used by other LVs. A copy\-on\-write snapshot LV can also +be reduced if less space is needed to hold COW blocks. Use +\fBlvconvert\fP(8) to change the number of data images in a RAID or +mirrored LV. + +Be careful when reducing an LV's size, because data in the reduced area is +lost. Ensure that any file system on the LV is resized \fBbefore\fP +running lvreduce so that the removed extents are not in use by the file +system. + +Sizes will be rounded if necessary. For example, the LV size must be an +exact number of extents, and the size of a striped segment must be a +multiple of the number of stripes. + +In the usage section below, \fB--size\fP \fISize\fP can be replaced +with \fB--extents\fP \fINumber\fP. See both descriptions +the options section. + diff --git a/man/lvreduce.8_end b/man/lvreduce.8_end new file mode 100644 index 0000000..59fde52 --- /dev/null +++ b/man/lvreduce.8_end @@ -0,0 +1,5 @@ +.SH EXAMPLES + +Reduce the size of an LV by 3 logical extents: +.br +.B lvreduce \-l \-3 vg00/lvol1 diff --git a/man/lvreduce.8_pregen b/man/lvreduce.8_pregen new file mode 100644 index 0000000..67c382b --- /dev/null +++ b/man/lvreduce.8_pregen @@ -0,0 +1,426 @@ +.TH LVREDUCE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvreduce \- Reduce the size of a logical volume +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvreduce\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +lvreduce reduces the size of an LV. The freed logical extents are returned +to the VG to be used by other LVs. A copy\-on\-write snapshot LV can also +be reduced if less space is needed to hold COW blocks. Use +\fBlvconvert\fP(8) to change the number of data images in a RAID or +mirrored LV. + +Be careful when reducing an LV's size, because data in the reduced area is +lost. Ensure that any file system on the LV is resized \fBbefore\fP +running lvreduce so that the removed extents are not in use by the file +system. + +Sizes will be rounded if necessary. For example, the LV size must be an +exact number of extents, and the size of a striped segment must be a +multiple of the number of stripes. + +In the usage section below, \fB--size\fP \fISize\fP can be replaced +with \fB--extents\fP \fINumber\fP. See both descriptions +the options section. + + +.P +.SH USAGE +.br +.P +. +\fBlvreduce\fP \fB-L\fP|\fB--size\fP [\fB-\fP]\fISize\fP[m|UNIT] \fILV\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP [\fB-\fP]\fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-n\fP|\fB--nofsck\fP ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--resizefs\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--extents\fP [\fB-\fP]\fINumber\fP[PERCENT] +.br +Specifies the new size of the LV in logical extents. +The --size and --extents options are alternate methods of specifying size. +The total number of physical extents used will be +greater when redundant data is needed for RAID levels. +An alternate syntax allows the size to be determined indirectly +as a percentage of the size of a related VG, LV, or set of PVs. The +suffix \fB%VG\fP denotes the total size of the VG, the suffix \fB%FREE\fP +the remaining free space in the VG, and the suffix \fB%PVS\fP the free +space in the specified PVs. For a snapshot, the size +can be expressed as a percentage of the total size of the origin LV +with the suffix \fB%ORIGIN\fP (\fB100%ORIGIN\fP provides space for +the whole origin). +When expressed as a percentage, the size defines an upper limit for the +number of logical extents in the new LV. The precise number of logical +extents in the new LV is not determined until the command has completed. +When the plus \fB+\fP or minus \fB-\fP prefix is used, +the value is not an absolute size, but is relative and added or subtracted +from the current size. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-n\fP|\fB--nofsck\fP +.br +Do not perform fsck before resizing filesystem when filesystem +requires it. You may need to use --force to proceed with +this option. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-r\fP|\fB--resizefs\fP +.br +Resize underlying filesystem together with the LV using fsadm(8). +.ad b + +.HP +.ad l +\fB-L\fP|\fB--size\fP [\fB-\fP]\fISize\fP[m|UNIT] +.br +Specifies the new size of the LV. +The --size and --extents options are alternate methods of specifying size. +The total number of physical extents used will be +greater when redundant data is needed for RAID levels. +When the plus \fB+\fP or minus \fB-\fP prefix is used, +the value is not an absolute size, but is relative and added or subtracted +from the current size. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Reduce the size of an LV by 3 logical extents: +.br +.B lvreduce \-l \-3 vg00/lvol1 +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvremove.8.des b/man/lvremove.8.des deleted file mode 100644 index 14587c1..0000000 --- a/man/lvremove.8.des +++ /dev/null @@ -1,27 +0,0 @@ -lvremove removes one or more LVs. For standard LVs, this returns the -logical extents that were used by the LV to the VG for use by other LVs. - -Confirmation will be requested before deactivating any active LV prior to -removal. LVs cannot be deactivated or removed while they are open (e.g. -if they contain a mounted filesystem). Removing an origin LV will also -remove all dependent snapshots. - -When a single force option is used, LVs are removed without confirmation, -and the command will try to deactivate unused LVs. - -To remove damaged LVs, two force options may be required (\fB-ff\fP). - -\fBHistorical LVs\fP - -If the configuration setting \fBmetadata/record_lvs_history\fP is enabled -and the LV being removed forms part of the history of at least one LV that -is still present, then a simplified representation of the LV will be -retained. This includes the time of removal (\fBlv_time_removed\fP -reporting field), creation time (\fBlv_time\fP), name (\fBlv_name\fP), LV -uuid (\fBlv_uuid\fP) and VG name (\fBvg_name\fP). This allows later -reporting to see the ancestry chain of thin snapshot volumes, even after -some intermediate LVs have been removed. The names of such historical LVs -acquire a hyphen as a prefix (e.g. '-lvol1') and cannot be reactivated. -Use lvremove a second time, with the hyphen, to remove the record of the -former LV completely. - diff --git a/man/lvremove.8.end b/man/lvremove.8.end deleted file mode 100644 index 5c70ed6..0000000 --- a/man/lvremove.8.end +++ /dev/null @@ -1,11 +0,0 @@ -.SH EXAMPLES - -Remove an active LV without asking for confirmation. -.br -.B lvremove \-f vg00/lvol1 - -Remove all LVs the specified VG. -.br -.B lvremove vg00 - - diff --git a/man/lvremove.8_des b/man/lvremove.8_des new file mode 100644 index 0000000..14587c1 --- /dev/null +++ b/man/lvremove.8_des @@ -0,0 +1,27 @@ +lvremove removes one or more LVs. For standard LVs, this returns the +logical extents that were used by the LV to the VG for use by other LVs. + +Confirmation will be requested before deactivating any active LV prior to +removal. LVs cannot be deactivated or removed while they are open (e.g. +if they contain a mounted filesystem). Removing an origin LV will also +remove all dependent snapshots. + +When a single force option is used, LVs are removed without confirmation, +and the command will try to deactivate unused LVs. + +To remove damaged LVs, two force options may be required (\fB-ff\fP). + +\fBHistorical LVs\fP + +If the configuration setting \fBmetadata/record_lvs_history\fP is enabled +and the LV being removed forms part of the history of at least one LV that +is still present, then a simplified representation of the LV will be +retained. This includes the time of removal (\fBlv_time_removed\fP +reporting field), creation time (\fBlv_time\fP), name (\fBlv_name\fP), LV +uuid (\fBlv_uuid\fP) and VG name (\fBvg_name\fP). This allows later +reporting to see the ancestry chain of thin snapshot volumes, even after +some intermediate LVs have been removed. The names of such historical LVs +acquire a hyphen as a prefix (e.g. '-lvol1') and cannot be reactivated. +Use lvremove a second time, with the hyphen, to remove the record of the +former LV completely. + diff --git a/man/lvremove.8_end b/man/lvremove.8_end new file mode 100644 index 0000000..5c70ed6 --- /dev/null +++ b/man/lvremove.8_end @@ -0,0 +1,11 @@ +.SH EXAMPLES + +Remove an active LV without asking for confirmation. +.br +.B lvremove \-f vg00/lvol1 + +Remove all LVs the specified VG. +.br +.B lvremove vg00 + + diff --git a/man/lvremove.8_pregen b/man/lvremove.8_pregen new file mode 100644 index 0000000..e823f1c --- /dev/null +++ b/man/lvremove.8_pregen @@ -0,0 +1,424 @@ +.TH LVREMOVE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvremove \- Remove logical volume(s) from the system +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvremove\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +lvremove removes one or more LVs. For standard LVs, this returns the +logical extents that were used by the LV to the VG for use by other LVs. + +Confirmation will be requested before deactivating any active LV prior to +removal. LVs cannot be deactivated or removed while they are open (e.g. +if they contain a mounted filesystem). Removing an origin LV will also +remove all dependent snapshots. + +When a single force option is used, LVs are removed without confirmation, +and the command will try to deactivate unused LVs. + +To remove damaged LVs, two force options may be required (\fB-ff\fP). + +\fBHistorical LVs\fP + +If the configuration setting \fBmetadata/record_lvs_history\fP is enabled +and the LV being removed forms part of the history of at least one LV that +is still present, then a simplified representation of the LV will be +retained. This includes the time of removal (\fBlv_time_removed\fP +reporting field), creation time (\fBlv_time\fP), name (\fBlv_name\fP), LV +uuid (\fBlv_uuid\fP) and VG name (\fBvg_name\fP). This allows later +reporting to see the ancestry chain of thin snapshot volumes, even after +some intermediate LVs have been removed. The names of such historical LVs +acquire a hyphen as a prefix (e.g. '-lvol1') and cannot be reactivated. +Use lvremove a second time, with the hyphen, to remove the record of the +former LV completely. + + +.P +.SH USAGE +.br +.P +. +\fBlvremove\fP \fIVG\fP|\fILV\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--nohistory\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--nohistory\fP +.br +Do not record history of LVs being removed. +This has no effect unless the configuration setting +metadata/record_lvs_history is enabled. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fISelect\fP +.br +Select indicates that a required positional parameter can +be omitted if the \fB--select\fP option is used. +No arg appears in this position. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Remove an active LV without asking for confirmation. +.br +.B lvremove \-f vg00/lvol1 + +Remove all LVs the specified VG. +.br +.B lvremove vg00 + + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvrename.8.des b/man/lvrename.8.des deleted file mode 100644 index a8455fc..0000000 --- a/man/lvrename.8.des +++ /dev/null @@ -1,2 +0,0 @@ -lvrename renames an existing LV or a historical LV (see \fBlvremove\fP for -historical LV information.) diff --git a/man/lvrename.8.end b/man/lvrename.8.end deleted file mode 100644 index 3409b8a..0000000 --- a/man/lvrename.8.end +++ /dev/null @@ -1,10 +0,0 @@ -.SH EXAMPLES - -Rename "lvold" to "lvnew": -.br -.B lvrename /dev/vg02/lvold vg02/lvnew - -An alternate syntax to rename "lvold" to "lvnew": -.br -.B lvrename vg02 lvold lvnew - diff --git a/man/lvrename.8_des b/man/lvrename.8_des new file mode 100644 index 0000000..a8455fc --- /dev/null +++ b/man/lvrename.8_des @@ -0,0 +1,2 @@ +lvrename renames an existing LV or a historical LV (see \fBlvremove\fP for +historical LV information.) diff --git a/man/lvrename.8_end b/man/lvrename.8_end new file mode 100644 index 0000000..3409b8a --- /dev/null +++ b/man/lvrename.8_end @@ -0,0 +1,10 @@ +.SH EXAMPLES + +Rename "lvold" to "lvnew": +.br +.B lvrename /dev/vg02/lvold vg02/lvnew + +An alternate syntax to rename "lvold" to "lvnew": +.br +.B lvrename vg02 lvold lvnew + diff --git a/man/lvrename.8_pregen b/man/lvrename.8_pregen new file mode 100644 index 0000000..20bdfbf --- /dev/null +++ b/man/lvrename.8_pregen @@ -0,0 +1,356 @@ +.TH LVRENAME 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvrename \- Rename a logical volume +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvrename\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +lvrename renames an existing LV or a historical LV (see \fBlvremove\fP for +historical LV information.) + +.P +.SH USAGE +.br +.P +. +\fBlvrename\fP \fIVG\fP \fILV\fP \fILV\fP\fI_new\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +\fBlvrename\fP \fILV\fP \fILV\fP\fI_new\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Rename "lvold" to "lvnew": +.br +.B lvrename /dev/vg02/lvold vg02/lvnew + +An alternate syntax to rename "lvold" to "lvnew": +.br +.B lvrename vg02 lvold lvnew + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvresize.8.des b/man/lvresize.8.des deleted file mode 100644 index 6f39ef7..0000000 --- a/man/lvresize.8.des +++ /dev/null @@ -1,7 +0,0 @@ -lvresize resizes an LV in the same way as lvextend and lvreduce. See -\fBlvextend\fP(8) and \fBlvreduce\fP(8) for more information. - -In the usage section below, \fB--size\fP \fISize\fP can be replaced -with \fB--extents\fP \fINumber\fP. See both descriptions -the options section. - diff --git a/man/lvresize.8.end b/man/lvresize.8.end deleted file mode 100644 index a336d62..0000000 --- a/man/lvresize.8.end +++ /dev/null @@ -1,6 +0,0 @@ -.SH EXAMPLES - -Extend an LV by 16MB using specific physical extents: -.br -.B lvresize \-L+16M vg1/lv1 /dev/sda:0\-1 /dev/sdb:0\-1 - diff --git a/man/lvresize.8_des b/man/lvresize.8_des new file mode 100644 index 0000000..6f39ef7 --- /dev/null +++ b/man/lvresize.8_des @@ -0,0 +1,7 @@ +lvresize resizes an LV in the same way as lvextend and lvreduce. See +\fBlvextend\fP(8) and \fBlvreduce\fP(8) for more information. + +In the usage section below, \fB--size\fP \fISize\fP can be replaced +with \fB--extents\fP \fINumber\fP. See both descriptions +the options section. + diff --git a/man/lvresize.8_end b/man/lvresize.8_end new file mode 100644 index 0000000..a336d62 --- /dev/null +++ b/man/lvresize.8_end @@ -0,0 +1,6 @@ +.SH EXAMPLES + +Extend an LV by 16MB using specific physical extents: +.br +.B lvresize \-L+16M vg1/lv1 /dev/sda:0\-1 /dev/sdb:0\-1 + diff --git a/man/lvresize.8_pregen b/man/lvresize.8_pregen new file mode 100644 index 0000000..598cde0 --- /dev/null +++ b/man/lvresize.8_pregen @@ -0,0 +1,702 @@ +.TH LVRESIZE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvresize \- Resize a logical volume +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvresize\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.P +.ad l + \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.ad b +.br +.ad l + \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--commandprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--config\fP \fIString\fP +.ad b +.br +.ad l + \fB-d\fP|\fB--debug\fP +.ad b +.br +.ad l + \fB--driverloaded\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-l\fP|\fB--extents\fP [\fB+\fP|\fB-\fP]\fINumber\fP[PERCENT] +.ad b +.br +.ad l + \fB-f\fP|\fB--force\fP +.ad b +.br +.ad l + \fB-h\fP|\fB--help\fP +.ad b +.br +.ad l + \fB--longhelp\fP +.ad b +.br +.ad l + \fB-n\fP|\fB--nofsck\fP +.ad b +.br +.ad l + \fB--nosync\fP +.ad b +.br +.ad l + \fB--noudevsync\fP +.ad b +.br +.ad l + \fB--poolmetadatasize\fP [\fB+\fP]\fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP +.ad b +.br +.ad l + \fB-q\fP|\fB--quiet\fP +.ad b +.br +.ad l + \fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.ad b +.br +.ad l + \fB-r\fP|\fB--resizefs\fP +.ad b +.br +.ad l + \fB-L\fP|\fB--size\fP [\fB+\fP|\fB-\fP]\fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB-i\fP|\fB--stripes\fP \fINumber\fP +.ad b +.br +.ad l + \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] +.ad b +.br +.ad l + \fB-t\fP|\fB--test\fP +.ad b +.br +.ad l + \fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP +.ad b +.br +.ad l + \fB-v\fP|\fB--verbose\fP +.ad b +.br +.ad l + \fB--version\fP +.ad b +.br +.ad l + \fB-y\fP|\fB--yes\fP +.ad b + +.P + +.SH DESCRIPTION +lvresize resizes an LV in the same way as lvextend and lvreduce. See +\fBlvextend\fP(8) and \fBlvreduce\fP(8) for more information. + +In the usage section below, \fB--size\fP \fISize\fP can be replaced +with \fB--extents\fP \fINumber\fP. See both descriptions +the options section. + + +.P +.SH USAGE +.br +.P +. +Resize an LV by a specified size. +.br +.P +\fBlvresize\fP \fB-L\fP|\fB--size\fP [\fB+\fP|\fB-\fP]\fISize\fP[m|UNIT] \fILV\fP +.br +.RS 4 +.ad l +[ \fB-l\fP|\fB--extents\fP [\fB+\fP|\fB-\fP]\fINumber\fP[PERCENT] ] +.ad b +.br +.ad l +[ \fB-r\fP|\fB--resizefs\fP ] +.ad b +.br +.ad l +[ \fB--poolmetadatasize\fP [\fB+\fP]\fISize\fP[m|UNIT] ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Resize an LV by specified PV extents. +.br +.P +\fBlvresize\fP \fILV\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB-r\fP|\fB--resizefs\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Resize a pool metadata SubLV by a specified size. +.br +.P +\fBlvresize\fP \fB--poolmetadatasize\fP [\fB+\fP]\fISize\fP[m|UNIT] \fILV\fP\fI_thinpool\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + +-- + +.br + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-n\fP|\fB--nofsck\fP ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--stripes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP ] +.ad b +.br +.ad l +[ \fB--nosync\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--extents\fP [\fB+\fP|\fB-\fP]\fINumber\fP[PERCENT] +.br +Specifies the new size of the LV in logical extents. +The --size and --extents options are alternate methods of specifying size. +The total number of physical extents used will be +greater when redundant data is needed for RAID levels. +An alternate syntax allows the size to be determined indirectly +as a percentage of the size of a related VG, LV, or set of PVs. The +suffix \fB%VG\fP denotes the total size of the VG, the suffix \fB%FREE\fP +the remaining free space in the VG, and the suffix \fB%PVS\fP the free +space in the specified PVs. For a snapshot, the size +can be expressed as a percentage of the total size of the origin LV +with the suffix \fB%ORIGIN\fP (\fB100%ORIGIN\fP provides space for +the whole origin). +When expressed as a percentage, the size defines an upper limit for the +number of logical extents in the new LV. The precise number of logical +extents in the new LV is not determined until the command has completed. +When the plus \fB+\fP or minus \fB-\fP prefix is used, +the value is not an absolute size, but is relative and added or subtracted +from the current size. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-n\fP|\fB--nofsck\fP +.br +Do not perform fsck before resizing filesystem when filesystem +requires it. You may need to use --force to proceed with +this option. +.ad b + +.HP +.ad l +\fB--nosync\fP +.br +Causes the creation of mirror, raid1, raid4, raid5 and raid10 to skip the +initial synchronization. In case of mirror, raid1 and raid10, any data +written afterwards will be mirrored, but the original contents will not be +copied. In case of raid4 and raid5, no parity blocks will be written, +though any data written afterwards will cause parity blocks to be stored. +This is useful for skipping a potentially long and resource intensive initial +sync of an empty mirror/raid1/raid4/raid5 and raid10 LV. +This option is not valid for raid6, because raid6 relies on proper parity +(P and Q Syndromes) being created during initial synchronization in order +to reconstruct proper user date in case of device failures. +raid0 and raid0_meta do not provide any data copies or parity support +and thus do not support initial synchronization. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB--poolmetadatasize\fP [\fB+\fP]\fISize\fP[m|UNIT] +.br +Specifies the new size of the pool metadata LV. +The plus prefix \fB+\fP can be used, in which case +the value is added to the current size. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-r\fP|\fB--resizefs\fP +.br +Resize underlying filesystem together with the LV using fsadm(8). +.ad b + +.HP +.ad l +\fB-L\fP|\fB--size\fP [\fB+\fP|\fB-\fP]\fISize\fP[m|UNIT] +.br +Specifies the new size of the LV. +The --size and --extents options are alternate methods of specifying size. +The total number of physical extents used will be +greater when redundant data is needed for RAID levels. +When the plus \fB+\fP or minus \fB-\fP prefix is used, +the value is not an absolute size, but is relative and added or subtracted +from the current size. +.ad b + +.HP +.ad l +\fB-i\fP|\fB--stripes\fP \fINumber\fP +.br +Specifies the number of stripes in a striped LV. This is the number of +PVs (devices) that a striped LV is spread across. Data that +appears sequential in the LV is spread across multiple devices in units of +the stripe size (see --stripesize). This does not change existing +allocated space, but only applies to space being allocated by the command. +When creating a RAID 4/5/6 LV, this number does not include the extra +devices that are required for parity. The largest number depends on +the RAID type (raid0: 64, raid10: 32, raid4/5: 63, raid6: 62), and +when unspecified, the default depends on the RAID type +(raid0: 2, raid10: 4, raid4/5: 3, raid6: 5.) +To stripe a new raid LV across all PVs by default, +see lvm.conf allocation/raid_stripe_all_devices. +.ad b + +.HP +.ad l +\fB-I\fP|\fB--stripesize\fP \fISize\fP[k|UNIT] +.br +The amount of data that is written to one device before +moving to the next in a striped LV. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--type\fP \fBlinear\fP|\fBstriped\fP|\fBsnapshot\fP|\fBmirror\fP|\fBraid\fP|\fBthin\fP|\fBcache\fP|\fBthin-pool\fP|\fBcache-pool\fP +.br +The LV type, also known as "segment type" or "segtype". +See usage descriptions for the specific ways to use these types. +For more information about redundancy and performance (\fBraid\fP, \fBmirror\fP, \fBstriped\fP, \fBlinear\fP) see \fBlvmraid\fP(7). +For thin provisioning (\fBthin\fP, \fBthin-pool\fP) see \fBlvmthin\fP(7). +For performance caching (\fBcache\fP, \fBcache-pool\fP) see \fBlvmcache\fP(7). +For copy-on-write snapshots (\fBsnapshot\fP) see usage definitions. +Several commands omit an explicit type option because the type +is inferred from other options or shortcuts +(e.g. --stripes, --mirrors, --snapshot, --virtualsize, --thin, --cache). +Use inferred types with care because it can lead to unexpected results. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. +LV followed by _ indicates that an LV of the +given type is required. (raid represents raid type) + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Extend an LV by 16MB using specific physical extents: +.br +.B lvresize \-L+16M vg1/lv1 /dev/sda:0\-1 /dev/sdb:0\-1 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvs.8.des b/man/lvs.8.des deleted file mode 100644 index 5f80764..0000000 --- a/man/lvs.8.des +++ /dev/null @@ -1 +0,0 @@ -lvs produces formatted output about LVs. diff --git a/man/lvs.8.end b/man/lvs.8.end deleted file mode 100644 index ff92148..0000000 --- a/man/lvs.8.end +++ /dev/null @@ -1,76 +0,0 @@ -.SH NOTES -. -The lv_attr bits are: -.IP 1 3 -Volume type: (C)ache, (m)irrored, (M)irrored without initial sync, (o)rigin, -(O)rigin with merging snapshot, (r)aid, (R)aid without initial sync, -(s)napshot, merging (S)napshot, (p)vmove, (v)irtual, -mirror or raid (i)mage, mirror or raid (I)mage out-of-sync, mirror (l)og device, -under (c)onversion, thin (V)olume, (t)hin pool, (T)hin pool data, raid or -pool m(e)tadata or pool metadata spare. -.IP 2 3 -Permissions: (w)riteable, (r)ead-only, (R)ead-only activation of non-read-only -volume -.IP 3 3 -Allocation policy: (a)nywhere, (c)ontiguous, (i)nherited, c(l)ing, (n)ormal -This is capitalised if the volume is currently locked against allocation -changes, for example during -.BR pvmove (8). -.IP 4 3 -fixed (m)inor -.IP 5 3 -State: (a)ctive, (h)istorical, (s)uspended, (I)nvalid snapshot, -invalid (S)uspended snapshot, snapshot (m)erge failed, -suspended snapshot (M)erge failed, mapped (d)evice present without tables, -mapped device present with (i)nactive table, thin-pool (c)heck needed, -suspended thin-pool (C)heck needed, (X) unknown -.IP 6 3 -device (o)pen, (X) unknown -.IP 7 3 -Target type: (C)ache, (m)irror, (r)aid, (s)napshot, (t)hin, (u)nknown, (v)irtual. -This groups logical volumes related to the same kernel target together. So, -for example, mirror images, mirror logs as well as mirrors themselves appear as -(m) if they use the original device-mapper mirror kernel driver; whereas the raid -equivalents using the md raid kernel driver all appear as (r). -Snapshots using the original device-mapper driver appear as (s); whereas -snapshots of thin volumes using the new thin provisioning driver appear as (t). -.IP 8 3 -Newly-allocated data blocks are overwritten with blocks of (z)eroes before use. -.IP 9 3 -Volume Health, where there are currently three groups of attributes identified: -.IP -Common ones for all Logical Volumes: (p)artial, (X) unknown. -.br -(p)artial signifies that one or more of the Physical Volumes this Logical -Volume uses is missing from the system. (X) unknown signifies the status -is unknown. -.IP -Related to RAID Logical Volumes: (r)efresh needed, (m)ismatches exist, (w)ritemostly. -.br -(r)efresh signifies that one or more of the Physical Volumes this RAID Logical -Volume uses had suffered a write error. The write error could be due to a -temporary failure of that Physical Volume or an indication that it is failing. -The device should be refreshed or replaced. (m)ismatches signifies that the -RAID logical volume has portions of the array that are not coherent. -Inconsistencies are detected by initiating a "check" on a RAID logical volume. -(The scrubbing operations, "check" and "repair", can be performed on a RAID -logical volume via the 'lvchange' command.) (w)ritemostly signifies the -devices in a RAID 1 logical volume that have been marked write-mostly. -(R)emove after reshape signifies freed striped raid images to be removed. -.IP -Related to Thin pool Logical Volumes: (F)ailed, out of (D)ata space, -(M)etadata read only. -.br -(F)ailed is set if thin pool encounters serious failures and hence no further I/O -is permitted at all. The out of (D)ata space is set if thin pool has run out of -data space. (M)etadata read only signifies that thin pool encounters certain -types of failures but it's still possible to do reads at least, -but no metadata changes are allowed. -.IP -Related to Thin Logical Volumes: (F)ailed. -.br -(F)ailed is set when related thin pool enters Failed state and no further I/O -is permitted at all. -.IP 10 3 -s(k)ip activation: this volume is flagged to be skipped during activation. - diff --git a/man/lvs.8_des b/man/lvs.8_des new file mode 100644 index 0000000..5f80764 --- /dev/null +++ b/man/lvs.8_des @@ -0,0 +1 @@ +lvs produces formatted output about LVs. diff --git a/man/lvs.8_end b/man/lvs.8_end new file mode 100644 index 0000000..ff92148 --- /dev/null +++ b/man/lvs.8_end @@ -0,0 +1,76 @@ +.SH NOTES +. +The lv_attr bits are: +.IP 1 3 +Volume type: (C)ache, (m)irrored, (M)irrored without initial sync, (o)rigin, +(O)rigin with merging snapshot, (r)aid, (R)aid without initial sync, +(s)napshot, merging (S)napshot, (p)vmove, (v)irtual, +mirror or raid (i)mage, mirror or raid (I)mage out-of-sync, mirror (l)og device, +under (c)onversion, thin (V)olume, (t)hin pool, (T)hin pool data, raid or +pool m(e)tadata or pool metadata spare. +.IP 2 3 +Permissions: (w)riteable, (r)ead-only, (R)ead-only activation of non-read-only +volume +.IP 3 3 +Allocation policy: (a)nywhere, (c)ontiguous, (i)nherited, c(l)ing, (n)ormal +This is capitalised if the volume is currently locked against allocation +changes, for example during +.BR pvmove (8). +.IP 4 3 +fixed (m)inor +.IP 5 3 +State: (a)ctive, (h)istorical, (s)uspended, (I)nvalid snapshot, +invalid (S)uspended snapshot, snapshot (m)erge failed, +suspended snapshot (M)erge failed, mapped (d)evice present without tables, +mapped device present with (i)nactive table, thin-pool (c)heck needed, +suspended thin-pool (C)heck needed, (X) unknown +.IP 6 3 +device (o)pen, (X) unknown +.IP 7 3 +Target type: (C)ache, (m)irror, (r)aid, (s)napshot, (t)hin, (u)nknown, (v)irtual. +This groups logical volumes related to the same kernel target together. So, +for example, mirror images, mirror logs as well as mirrors themselves appear as +(m) if they use the original device-mapper mirror kernel driver; whereas the raid +equivalents using the md raid kernel driver all appear as (r). +Snapshots using the original device-mapper driver appear as (s); whereas +snapshots of thin volumes using the new thin provisioning driver appear as (t). +.IP 8 3 +Newly-allocated data blocks are overwritten with blocks of (z)eroes before use. +.IP 9 3 +Volume Health, where there are currently three groups of attributes identified: +.IP +Common ones for all Logical Volumes: (p)artial, (X) unknown. +.br +(p)artial signifies that one or more of the Physical Volumes this Logical +Volume uses is missing from the system. (X) unknown signifies the status +is unknown. +.IP +Related to RAID Logical Volumes: (r)efresh needed, (m)ismatches exist, (w)ritemostly. +.br +(r)efresh signifies that one or more of the Physical Volumes this RAID Logical +Volume uses had suffered a write error. The write error could be due to a +temporary failure of that Physical Volume or an indication that it is failing. +The device should be refreshed or replaced. (m)ismatches signifies that the +RAID logical volume has portions of the array that are not coherent. +Inconsistencies are detected by initiating a "check" on a RAID logical volume. +(The scrubbing operations, "check" and "repair", can be performed on a RAID +logical volume via the 'lvchange' command.) (w)ritemostly signifies the +devices in a RAID 1 logical volume that have been marked write-mostly. +(R)emove after reshape signifies freed striped raid images to be removed. +.IP +Related to Thin pool Logical Volumes: (F)ailed, out of (D)ata space, +(M)etadata read only. +.br +(F)ailed is set if thin pool encounters serious failures and hence no further I/O +is permitted at all. The out of (D)ata space is set if thin pool has run out of +data space. (M)etadata read only signifies that thin pool encounters certain +types of failures but it's still possible to do reads at least, +but no metadata changes are allowed. +.IP +Related to Thin Logical Volumes: (F)ailed. +.br +(F)ailed is set when related thin pool enters Failed state and no further I/O +is permitted at all. +.IP 10 3 +s(k)ip activation: this volume is flagged to be skipped during activation. + diff --git a/man/lvs.8_pregen b/man/lvs.8_pregen new file mode 100644 index 0000000..2abe377 --- /dev/null +++ b/man/lvs.8_pregen @@ -0,0 +1,733 @@ +.TH LVS 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvs \- Display information about logical volumes +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvs\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +lvs produces formatted output about LVs. + +.P +.SH USAGE +.br +.P +. +\fBlvs\fP +.br +.RS 4 +.ad l +[ \fB-H\fP|\fB--history\fP ] +.ad b +.br +.ad l +[ \fB-a\fP|\fB--all\fP ] +.ad b +.br +.ad l +[ \fB-o\fP|\fB--options\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-O\fP|\fB--sort\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--segments\fP ] +.ad b +.br +.ad l +[ \fB--aligned\fP ] +.ad b +.br +.ad l +[ \fB--binary\fP ] +.ad b +.br +.ad l +[ \fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP ] +.ad b +.br +.ad l +[ \fB--foreign\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--logonly\fP ] +.ad b +.br +.ad l +[ \fB--nameprefixes\fP ] +.ad b +.br +.ad l +[ \fB--noheadings\fP ] +.ad b +.br +.ad l +[ \fB--nolocking\fP ] +.ad b +.br +.ad l +[ \fB--nosuffix\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--rows\fP ] +.ad b +.br +.ad l +[ \fB--separator\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--shared\fP ] +.ad b +.br +.ad l +[ \fB--trustcache\fP ] +.ad b +.br +.ad l +[ \fB--unbuffered\fP ] +.ad b +.br +.ad l +[ \fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP ] +.ad b +.br +.ad l +[ \fB--unquoted\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fILV\fP|\fITag\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--aligned\fP +.br +Use with --separator to align the output columns +.ad b + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +Show information about internal LVs. +These are components of normal LVs, such as mirrors, +which are not independently accessible, e.g. not mountable. +.ad b + +.HP +.ad l +\fB--binary\fP +.br +Use binary values "0" or "1" instead of descriptive literal values +for columns that have exactly two valid values to report (not counting +the "unknown" value which denotes that the value could not be determined). +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--foreign\fP +.br +Report/display foreign VGs that would otherwise be skipped. +See lvmsystemid(7) for more information about foreign VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-H\fP|\fB--history\fP +.br +Include historical LVs in the output. +(This has no effect unless LVs were removed while +lvm.conf metadata/record_lvs_history was enabled. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--logonly\fP +.br +Suppress command report and display only log report. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--nameprefixes\fP +.br +Add an "LVM2_" prefix plus the field name to the output. Useful +with --noheadings to produce a list of field=value pairs that can +be used to set environment variables (for example, in udev rules). +.ad b + +.HP +.ad l +\fB--noheadings\fP +.br +Suppress the headings line that is normally the first line of output. +Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--nolocking\fP +.br +Disable locking. +.ad b + +.HP +.ad l +\fB--nosuffix\fP +.br +Suppress the suffix on output sizes. Use with --units +(except h and H) if processing the output. +.ad b + +.HP +.ad l +\fB-o\fP|\fB--options\fP \fIString\fP +.br +Comma-separated, ordered list of fields to display in columns. +String arg syntax is: [+|-|#]Field1[,Field2 ...] +The prefix \fB+\fP will append the specified fields to the default fields, +\fB-\fP will remove the specified fields from the default fields, and +\fB#\fP will compact specified fields (removing them when empty for all rows.) +Use \fB-o help\fP to view the list of all available fields. +The -o option can be repeated, providing several lists. +These lists are evaluated from left to right. +Use field name \fBlv_all\fP to view all LV fields, +\fBvg_all\fP all VG fields, +\fBpv_all\fP all PV fields, +\fBpvseg_all\fP all PV segment fields, +\fBseg_all\fP all LV segment fields, and +\fBpvseg_all\fP all PV segment columns. +See the lvm.conf report section for more config options. +See lvmreport(7) for more information about reporting. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--rows\fP +.br +Output columns as rows. +.ad b + +.HP +.ad l +\fB--segments\fP +.br +Use default columns that emphasize segment information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB--separator\fP \fIString\fP +.br +String to use to separate each column. Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--shared\fP +.br +Report/display shared VGs that would otherwise be skipped when +lvmlockd is not being used on the host. +See lvmlockd(8) for more information about shared VGs. +.ad b + +.HP +.ad l +\fB-O\fP|\fB--sort\fP \fIString\fP +.br +Comma-separated ordered list of columns to sort by. Replaces the default +selection. Precede any column with \fB-\fP for a reverse sort on that column. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--trustcache\fP +.br +Avoids certain device scanning during command processing. Do not use. +.ad b + +.HP +.ad l +\fB--unbuffered\fP +.br +Produce output immediately without sorting or aligning the columns properly. +.ad b + +.HP +.ad l +\fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP +.br +All sizes are output in these units: +human-(r)eadable with '<' rounding indicator, +(h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, +(g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. +Capitalise to use multiples of 1000 (S.I.) instead of 1024. +Custom units can be specified, e.g. --units 3M. +.ad b + +.HP +.ad l +\fB--unquoted\fP +.br +When used with --nameprefixes, output values in the field=value +pairs are not quoted. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH NOTES +. +The lv_attr bits are: +.IP 1 3 +Volume type: (C)ache, (m)irrored, (M)irrored without initial sync, (o)rigin, +(O)rigin with merging snapshot, (r)aid, (R)aid without initial sync, +(s)napshot, merging (S)napshot, (p)vmove, (v)irtual, +mirror or raid (i)mage, mirror or raid (I)mage out-of-sync, mirror (l)og device, +under (c)onversion, thin (V)olume, (t)hin pool, (T)hin pool data, raid or +pool m(e)tadata or pool metadata spare. +.IP 2 3 +Permissions: (w)riteable, (r)ead-only, (R)ead-only activation of non-read-only +volume +.IP 3 3 +Allocation policy: (a)nywhere, (c)ontiguous, (i)nherited, c(l)ing, (n)ormal +This is capitalised if the volume is currently locked against allocation +changes, for example during +.BR pvmove (8). +.IP 4 3 +fixed (m)inor +.IP 5 3 +State: (a)ctive, (h)istorical, (s)uspended, (I)nvalid snapshot, +invalid (S)uspended snapshot, snapshot (m)erge failed, +suspended snapshot (M)erge failed, mapped (d)evice present without tables, +mapped device present with (i)nactive table, thin-pool (c)heck needed, +suspended thin-pool (C)heck needed, (X) unknown +.IP 6 3 +device (o)pen, (X) unknown +.IP 7 3 +Target type: (C)ache, (m)irror, (r)aid, (s)napshot, (t)hin, (u)nknown, (v)irtual. +This groups logical volumes related to the same kernel target together. So, +for example, mirror images, mirror logs as well as mirrors themselves appear as +(m) if they use the original device-mapper mirror kernel driver; whereas the raid +equivalents using the md raid kernel driver all appear as (r). +Snapshots using the original device-mapper driver appear as (s); whereas +snapshots of thin volumes using the new thin provisioning driver appear as (t). +.IP 8 3 +Newly-allocated data blocks are overwritten with blocks of (z)eroes before use. +.IP 9 3 +Volume Health, where there are currently three groups of attributes identified: +.IP +Common ones for all Logical Volumes: (p)artial, (X) unknown. +.br +(p)artial signifies that one or more of the Physical Volumes this Logical +Volume uses is missing from the system. (X) unknown signifies the status +is unknown. +.IP +Related to RAID Logical Volumes: (r)efresh needed, (m)ismatches exist, (w)ritemostly. +.br +(r)efresh signifies that one or more of the Physical Volumes this RAID Logical +Volume uses had suffered a write error. The write error could be due to a +temporary failure of that Physical Volume or an indication that it is failing. +The device should be refreshed or replaced. (m)ismatches signifies that the +RAID logical volume has portions of the array that are not coherent. +Inconsistencies are detected by initiating a "check" on a RAID logical volume. +(The scrubbing operations, "check" and "repair", can be performed on a RAID +logical volume via the 'lvchange' command.) (w)ritemostly signifies the +devices in a RAID 1 logical volume that have been marked write-mostly. +(R)emove after reshape signifies freed striped raid images to be removed. +.IP +Related to Thin pool Logical Volumes: (F)ailed, out of (D)ata space, +(M)etadata read only. +.br +(F)ailed is set if thin pool encounters serious failures and hence no further I/O +is permitted at all. The out of (D)ata space is set if thin pool has run out of +data space. (M)etadata read only signifies that thin pool encounters certain +types of failures but it's still possible to do reads at least, +but no metadata changes are allowed. +.IP +Related to Thin Logical Volumes: (F)ailed. +.br +(F)ailed is set when related thin pool enters Failed state and no further I/O +is permitted at all. +.IP 10 3 +s(k)ip activation: this volume is flagged to be skipped during activation. + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/lvscan.8.des b/man/lvscan.8.des deleted file mode 100644 index e30eb58..0000000 --- a/man/lvscan.8.des +++ /dev/null @@ -1,5 +0,0 @@ -lvscan scans all VGs or all supported LVM block devices in the system for -LVs. The output consists of one line for each LV indicating whether or not -it is active, a snapshot or origin, the size of the device and its -allocation policy. Use \fBlvs\fP(8) or \fBlvdisplay\fP(8) to obtain more -comprehensive information about LVs. diff --git a/man/lvscan.8_des b/man/lvscan.8_des new file mode 100644 index 0000000..e30eb58 --- /dev/null +++ b/man/lvscan.8_des @@ -0,0 +1,5 @@ +lvscan scans all VGs or all supported LVM block devices in the system for +LVs. The output consists of one line for each LV indicating whether or not +it is active, a snapshot or origin, the size of the device and its +allocation policy. Use \fBlvs\fP(8) or \fBlvdisplay\fP(8) to obtain more +comprehensive information about LVs. diff --git a/man/lvscan.8_end b/man/lvscan.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/lvscan.8_pregen b/man/lvscan.8_pregen new file mode 100644 index 0000000..421b6c5 --- /dev/null +++ b/man/lvscan.8_pregen @@ -0,0 +1,399 @@ +.TH LVSCAN 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +lvscan \- List all logical volumes in all volume groups +.P +. +.SH SYNOPSIS +.br +.P +. +\fBlvscan\fP \fIoption_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +lvscan scans all VGs or all supported LVM block devices in the system for +LVs. The output consists of one line for each LV indicating whether or not +it is active, a snapshot or origin, the size of the device and its +allocation policy. Use \fBlvs\fP(8) or \fBlvdisplay\fP(8) to obtain more +comprehensive information about LVs. + +.P +.SH USAGE +.br +.P +. +\fBlvscan\fP +.br +.RS 4 +.ad l +[ \fB-a\fP|\fB--all\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +\fBlvscan\fP \fB--cache\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fILV\fP ... ] +.RE + + +Common options for command: +. +.RS 4 +.ad l +[ \fB-b\fP|\fB--blockdevice\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +Show information about internal LVs. +These are components of normal LVs, such as mirrors, +which are not independently accessible, e.g. not mountable. +.ad b + +.HP +.ad l +\fB-b\fP|\fB--blockdevice\fP +.br +No longer used. +.ad b + +.HP +.ad l +\fB--cache\fP +.br +Scan the devices used by an LV and send the metadata to lvmetad. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvchange.8.des b/man/pvchange.8.des deleted file mode 100644 index 802850f..0000000 --- a/man/pvchange.8.des +++ /dev/null @@ -1 +0,0 @@ -pvchange changes PV attributes in the VG. diff --git a/man/pvchange.8.end b/man/pvchange.8.end deleted file mode 100644 index a524d07..0000000 --- a/man/pvchange.8.end +++ /dev/null @@ -1,6 +0,0 @@ -.SH EXAMPLES - -Disallow the allocation of physical extents on a PV (e.g. because of -disk errors, or because it will be removed after freeing it). -.br -.B pvchange \-x n /dev/sdk1 diff --git a/man/pvchange.8_des b/man/pvchange.8_des new file mode 100644 index 0000000..802850f --- /dev/null +++ b/man/pvchange.8_des @@ -0,0 +1 @@ +pvchange changes PV attributes in the VG. diff --git a/man/pvchange.8_end b/man/pvchange.8_end new file mode 100644 index 0000000..a524d07 --- /dev/null +++ b/man/pvchange.8_end @@ -0,0 +1,6 @@ +.SH EXAMPLES + +Disallow the allocation of physical extents on a PV (e.g. because of +disk errors, or because it will be removed after freeing it). +.br +.B pvchange \-x n /dev/sdk1 diff --git a/man/pvchange.8_pregen b/man/pvchange.8_pregen new file mode 100644 index 0000000..1b72672 --- /dev/null +++ b/man/pvchange.8_pregen @@ -0,0 +1,487 @@ +.TH PVCHANGE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvchange \- Change attributes of physical volume(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvchange\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +pvchange changes PV attributes in the VG. + +.P +.SH USAGE +.br +.P +. +Change properties of all PVs. +.br +.P +\fBpvchange\fP +.RS 4 +( \fB-x\fP|\fB--allocatable\fP \fBy\fP|\fBn\fP, +.ad b +.br +.ad l + \fB-u\fP|\fB--uuid\fP, +.ad b +.br +.ad l + \fB-a\fP|\fB--all\fP, +.ad b +.br +.ad l + \fB--addtag\fP \fITag\fP, +.ad b +.br +.ad l + \fB--deltag\fP \fITag\fP, +.ad b +.br +.ad l + \fB--metadataignore\fP \fBy\fP|\fBn\fP ) +.RE +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Change properties of specified PVs. +.br +.P +\fBpvchange\fP +.RS 4 +( \fB-x\fP|\fB--allocatable\fP \fBy\fP|\fBn\fP, +.ad b +.br +.ad l + \fB-u\fP|\fB--uuid\fP, +.ad b +.br +.ad l + \fB--addtag\fP \fITag\fP, +.ad b +.br +.ad l + \fB--deltag\fP \fITag\fP, +.ad b +.br +.ad l + \fB--metadataignore\fP \fBy\fP|\fBn\fP ) +.RE +.RS 4 + \fIPV\fP|\fISelect\fP ... +.RE +.br +.RS 4 +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-u\fP|\fB--uuid\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--addtag\fP \fITag\fP +.br +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. +.ad b + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +.ad b + +.HP +.ad l +\fB-x\fP|\fB--allocatable\fP \fBy\fP|\fBn\fP +.br +Enable or disable allocation of physical extents on this PV. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--deltag\fP \fITag\fP +.br +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. +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--metadataignore\fP \fBy\fP|\fBn\fP +.br +Specifies the metadataignore property of a PV. +If yes, metadata areas on the PV are ignored, and lvm will +not store metadata in the metadata areas of the PV. +If no, lvm will store metadata on the PV. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-u\fP|\fB--uuid\fP +.br +Generate new random UUID for specified PVs. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fISelect\fP +.br +Select indicates that a required positional parameter can +be omitted if the \fB--select\fP option is used. +No arg appears in this position. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Disallow the allocation of physical extents on a PV (e.g. because of +disk errors, or because it will be removed after freeing it). +.br +.B pvchange \-x n /dev/sdk1 +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvck.8.des b/man/pvck.8.des deleted file mode 100644 index 0a32657..0000000 --- a/man/pvck.8.des +++ /dev/null @@ -1 +0,0 @@ -pvck checks the LVM metadata for consistency on PVs. diff --git a/man/pvck.8.end b/man/pvck.8.end deleted file mode 100644 index 67af238..0000000 --- a/man/pvck.8.end +++ /dev/null @@ -1,8 +0,0 @@ -.SH EXAMPLES - -If the partition table is corrupted or lost on /dev/sda, and you suspect -there was an LVM partition at approximately 100 MiB, then this -area of the disk can be scanned using the \fB\-\-labelsector\fP -parameter with a value of 204800 (100 * 1024 * 1024 / 512 = 204800). -.br -.B pvck \-\-labelsector 204800 /dev/sda diff --git a/man/pvck.8_des b/man/pvck.8_des new file mode 100644 index 0000000..0a32657 --- /dev/null +++ b/man/pvck.8_des @@ -0,0 +1 @@ +pvck checks the LVM metadata for consistency on PVs. diff --git a/man/pvck.8_end b/man/pvck.8_end new file mode 100644 index 0000000..67af238 --- /dev/null +++ b/man/pvck.8_end @@ -0,0 +1,8 @@ +.SH EXAMPLES + +If the partition table is corrupted or lost on /dev/sda, and you suspect +there was an LVM partition at approximately 100 MiB, then this +area of the disk can be scanned using the \fB\-\-labelsector\fP +parameter with a value of 204800 (100 * 1024 * 1024 / 512 = 204800). +.br +.B pvck \-\-labelsector 204800 /dev/sda diff --git a/man/pvck.8_pregen b/man/pvck.8_pregen new file mode 100644 index 0000000..a420953 --- /dev/null +++ b/man/pvck.8_pregen @@ -0,0 +1,311 @@ +.TH PVCK 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvck \- Check the consistency of physical volume(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvck\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +pvck checks the LVM metadata for consistency on PVs. + +.P +.SH USAGE +.br +.P +. +\fBpvck\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB--labelsector\fP \fINumber\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--labelsector\fP \fINumber\fP +.br +By default the PV is labelled with an LVM2 identifier in its second +sector (sector 1). This lets you use a different sector near the +start of the disk (between 0 and 3 inclusive - see LABEL_SCAN_SECTORS +in the source). Use with care. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +If the partition table is corrupted or lost on /dev/sda, and you suspect +there was an LVM partition at approximately 100 MiB, then this +area of the disk can be scanned using the \fB\-\-labelsector\fP +parameter with a value of 204800 (100 * 1024 * 1024 / 512 = 204800). +.br +.B pvck \-\-labelsector 204800 /dev/sda +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvcreate.8.des b/man/pvcreate.8.des deleted file mode 100644 index 1b00e9e..0000000 --- a/man/pvcreate.8.des +++ /dev/null @@ -1,21 +0,0 @@ -pvcreate initializes a PV so that it is recognized as belonging to LVM, -and allows the PV to be used in a VG. A PV can be a disk partition, whole -disk, meta device, or loopback file. - -For DOS disk partitions, the partition id should be set to 0x8e using -.BR fdisk (8), -.BR cfdisk (8), -or a equivalent. For GUID Partition Table (GPT), the id is -E6D6D379-F507-44C2-A23C-238F2A3DF928. For -whole disk devices only -the partition table must be erased, which will effectively destroy all -data on that disk. This can be done by zeroing the first sector with: - -.BI "dd if=/dev/zero of=" PhysicalVolume " bs=512 count=1" - -Use \fBvgcreate\fP(8) to create a new VG on the PV, or \fBvgextend\fP(8) -to add the PV to existing VG. - -The force option will create a PV without confirmation. Repeating the -force option (\fB-ff\fP) will forcibly create a PV, overriding checks that -normally prevent it, e.g. if the PV is already in a VG. diff --git a/man/pvcreate.8.end b/man/pvcreate.8.end deleted file mode 100644 index b1b0f3e..0000000 --- a/man/pvcreate.8.end +++ /dev/null @@ -1,13 +0,0 @@ -.SH EXAMPLES - -Initialize a partition and a full device. -.br -.B pvcreate /dev/sdc4 /dev/sde - -If a device is a 4KiB sector drive that compensates for windows -partitioning (sector 7 is the lowest aligned logical block, the 4KiB -sectors start at LBA -1, and consequently sector 63 is aligned on a 4KiB -boundary) manually account for this when initializing for use by LVM. -.br -.B pvcreate \-\-dataalignmentoffset 7s /dev/sdb - diff --git a/man/pvcreate.8_des b/man/pvcreate.8_des new file mode 100644 index 0000000..1b00e9e --- /dev/null +++ b/man/pvcreate.8_des @@ -0,0 +1,21 @@ +pvcreate initializes a PV so that it is recognized as belonging to LVM, +and allows the PV to be used in a VG. A PV can be a disk partition, whole +disk, meta device, or loopback file. + +For DOS disk partitions, the partition id should be set to 0x8e using +.BR fdisk (8), +.BR cfdisk (8), +or a equivalent. For GUID Partition Table (GPT), the id is +E6D6D379-F507-44C2-A23C-238F2A3DF928. For +whole disk devices only +the partition table must be erased, which will effectively destroy all +data on that disk. This can be done by zeroing the first sector with: + +.BI "dd if=/dev/zero of=" PhysicalVolume " bs=512 count=1" + +Use \fBvgcreate\fP(8) to create a new VG on the PV, or \fBvgextend\fP(8) +to add the PV to existing VG. + +The force option will create a PV without confirmation. Repeating the +force option (\fB-ff\fP) will forcibly create a PV, overriding checks that +normally prevent it, e.g. if the PV is already in a VG. diff --git a/man/pvcreate.8_end b/man/pvcreate.8_end new file mode 100644 index 0000000..b1b0f3e --- /dev/null +++ b/man/pvcreate.8_end @@ -0,0 +1,13 @@ +.SH EXAMPLES + +Initialize a partition and a full device. +.br +.B pvcreate /dev/sdc4 /dev/sde + +If a device is a 4KiB sector drive that compensates for windows +partitioning (sector 7 is the lowest aligned logical block, the 4KiB +sectors start at LBA -1, and consequently sector 63 is aligned on a 4KiB +boundary) manually account for this when initializing for use by LVM. +.br +.B pvcreate \-\-dataalignmentoffset 7s /dev/sdb + diff --git a/man/pvcreate.8_pregen b/man/pvcreate.8_pregen new file mode 100644 index 0000000..0cf7549 --- /dev/null +++ b/man/pvcreate.8_pregen @@ -0,0 +1,539 @@ +.TH PVCREATE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvcreate \- Initialize physical volume(s) for use by LVM +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvcreate\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +pvcreate initializes a PV so that it is recognized as belonging to LVM, +and allows the PV to be used in a VG. A PV can be a disk partition, whole +disk, meta device, or loopback file. + +For DOS disk partitions, the partition id should be set to 0x8e using +.BR fdisk (8), +.BR cfdisk (8), +or a equivalent. For GUID Partition Table (GPT), the id is +E6D6D379-F507-44C2-A23C-238F2A3DF928. For +whole disk devices only +the partition table must be erased, which will effectively destroy all +data on that disk. This can be done by zeroing the first sector with: + +.BI "dd if=/dev/zero of=" PhysicalVolume " bs=512 count=1" + +Use \fBvgcreate\fP(8) to create a new VG on the PV, or \fBvgextend\fP(8) +to add the PV to existing VG. + +The force option will create a PV without confirmation. Repeating the +force option (\fB-ff\fP) will forcibly create a PV, overriding checks that +normally prevent it, e.g. if the PV is already in a VG. + +.P +.SH USAGE +.br +.P +. +\fBpvcreate\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP ] +.ad b +.br +.ad l +[ \fB-u\fP|\fB--uuid\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--dataalignment\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--dataalignmentoffset\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--bootloaderareasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--labelsector\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--[pv]metadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +.ad l +[ \fB--metadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--metadataignore\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--norestorefile\fP ] +.ad b +.br +.ad l +[ \fB--setphysicalvolumesize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--restorefile\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--bootloaderareasize\fP \fISize\fP[m|UNIT] +.br +Create a separate bootloader area of specified size besides PV's data +area. The bootloader area is an area of reserved space on the PV from +which LVM will not allocate any extents and it's kept untouched. This is +primarily aimed for use with bootloaders to embed their own data or metadata. +The start of the bootloader area is always aligned, see also --dataalignment +and --dataalignmentoffset. The bootloader area size may eventually +end up increased due to the alignment, but it's never less than the +size that is requested. To see the bootloader area start and size of +an existing PV use pvs -o +pv_ba_start,pv_ba_size. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--dataalignment\fP \fISize\fP[k|UNIT] +.br +Align the start of the data to a multiple of this number. +Also specify an appropriate Physical Extent size when creating a VG. +To see the location of the first Physical Extent of an existing PV, +use pvs -o +pe_start. In addition, it may be shifted by an alignment offset. +See lvm.conf/data_alignment_offset_detection and --dataalignmentoffset. +.ad b + +.HP +.ad l +\fB--dataalignmentoffset\fP \fISize\fP[k|UNIT] +.br +Shift the start of the data area by this additional offset. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--labelsector\fP \fINumber\fP +.br +By default the PV is labelled with an LVM2 identifier in its second +sector (sector 1). This lets you use a different sector near the +start of the disk (between 0 and 3 inclusive - see LABEL_SCAN_SECTORS +in the source). Use with care. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--metadataignore\fP \fBy\fP|\fBn\fP +.br +Specifies the metadataignore property of a PV. +If yes, metadata areas on the PV are ignored, and lvm will +not store metadata in the metadata areas of the PV. +If no, lvm will store metadata on the PV. +.ad b + +.HP +.ad l +\fB--metadatasize\fP \fISize\fP[m|UNIT] +.br +The approximate amount of space used for each VG metadata area. +The size may be rounded. +.ad b + +.HP +.ad l +\fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP +.br +Specifies the type of on-disk metadata to use. +\fBlvm2\fP (or just \fB2\fP) is the current, standard format. +\fBlvm1\fP (or just \fB1\fP) is a historical format that +can be used for accessing old data. +.ad b + +.HP +.ad l +\fB--norestorefile\fP +.br +In conjunction with --uuid, this allows a uuid to be specified +without also requiring that a backup of the metadata be provided. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB--[pv]metadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP +.br +The number of metadata areas to set aside on a PV for storing VG metadata. +When 2, one copy of the VG metadata is stored at the front of the PV +and a second copy is stored at the end. +When 1, one copy of the VG metadata is stored at the front of the PV +(starting in the 5th sector). +When 0, no copies of the VG metadata are stored on the given PV. +This may be useful in VGs containing many PVs (this places limitations +on the ability to use vgsplit later.) +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--restorefile\fP \fIString\fP +.br +In conjunction with --uuid, this reads the file (produced by +vgcfgbackup), extracts the location and size of the data on the PV, +and ensures that the metadata produced by the program is consistent +with the contents of the file, i.e. the physical extents will be in +the same place and not be overwritten by new metadata. This provides +a mechanism to upgrade the metadata format or to add/remove metadata +areas. Use with care. +.ad b + +.HP +.ad l +\fB--setphysicalvolumesize\fP \fISize\fP[m|UNIT] +.br +Overrides the automatically detected size of the PV. +Use with care, or prior to reducing the physical size of the device. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-u\fP|\fB--uuid\fP \fIString\fP +.br +Specify a UUID for the device. +Without this option, a random UUID is generated. +This option is needed before restoring a backup of LVM metadata +onto a replacement device; see vgcfgrestore(8). As such, use of +--restorefile is compulsory unless the --norestorefile is used. +All PVs must have unique UUIDs, and LVM will prevent certain operations +if multiple devices are seen with the same UUID. +See vgimportclone(8) for more information. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b + +.HP +.ad l +\fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.br +Controls if the first 4 sectors (2048 bytes) of the device are wiped. +The default is to wipe these sectors unless either or both of +--restorefile or --uuid are specified. +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Initialize a partition and a full device. +.br +.B pvcreate /dev/sdc4 /dev/sde + +If a device is a 4KiB sector drive that compensates for windows +partitioning (sector 7 is the lowest aligned logical block, the 4KiB +sectors start at LBA -1, and consequently sector 63 is aligned on a 4KiB +boundary) manually account for this when initializing for use by LVM. +.br +.B pvcreate \-\-dataalignmentoffset 7s /dev/sdb + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvdisplay.8.des b/man/pvdisplay.8.des deleted file mode 100644 index 74d57ca..0000000 --- a/man/pvdisplay.8.des +++ /dev/null @@ -1,5 +0,0 @@ -pvdisplay shows the attributes of PVs, like size, physical extent size, -space used for the VG descriptor area, etc. - -\fBpvs\fP(8) is a preferred alternative that shows the same information -and more, using a more compact and configurable output format. diff --git a/man/pvdisplay.8_des b/man/pvdisplay.8_des new file mode 100644 index 0000000..74d57ca --- /dev/null +++ b/man/pvdisplay.8_des @@ -0,0 +1,5 @@ +pvdisplay shows the attributes of PVs, like size, physical extent size, +space used for the VG descriptor area, etc. + +\fBpvs\fP(8) is a preferred alternative that shows the same information +and more, using a more compact and configurable output format. diff --git a/man/pvdisplay.8_end b/man/pvdisplay.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/pvdisplay.8_pregen b/man/pvdisplay.8_pregen new file mode 100644 index 0000000..9e793b9 --- /dev/null +++ b/man/pvdisplay.8_pregen @@ -0,0 +1,610 @@ +.TH PVDISPLAY 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvdisplay \- Display various attributes of physical volume(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvdisplay\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +pvdisplay shows the attributes of PVs, like size, physical extent size, +space used for the VG descriptor area, etc. + +\fBpvs\fP(8) is a preferred alternative that shows the same information +and more, using a more compact and configurable output format. + +.P +.SH USAGE +.br +.P +. +\fBpvdisplay\fP +.br +.RS 4 +.ad l +[ \fB-a\fP|\fB--all\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--colon\fP ] +.ad b +.br +.ad l +[ \fB-C\fP|\fB--columns\fP ] +.ad b +.br +.ad l +[ \fB-m\fP|\fB--maps\fP ] +.ad b +.br +.ad l +[ \fB-o\fP|\fB--options\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-s\fP|\fB--short\fP ] +.ad b +.br +.ad l +[ \fB-O\fP|\fB--sort\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--aligned\fP ] +.ad b +.br +.ad l +[ \fB--binary\fP ] +.ad b +.br +.ad l +[ \fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP ] +.ad b +.br +.ad l +[ \fB--foreign\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--logonly\fP ] +.ad b +.br +.ad l +[ \fB--noheadings\fP ] +.ad b +.br +.ad l +[ \fB--nosuffix\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--separator\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--shared\fP ] +.ad b +.br +.ad l +[ \fB--unbuffered\fP ] +.ad b +.br +.ad l +[ \fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP|\fITag\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--aligned\fP +.br +Use with --separator to align the output columns +.ad b + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +Show information about devices that have not been initialized +by LVM, i.e. they are not PVs. +.ad b + +.HP +.ad l +\fB--binary\fP +.br +Use binary values "0" or "1" instead of descriptive literal values +for columns that have exactly two valid values to report (not counting +the "unknown" value which denotes that the value could not be determined). +.ad b + +.HP +.ad l +\fB-c\fP|\fB--colon\fP +.br +Generate colon separated output for easier parsing in scripts or programs. +Also see vgs(8) which provides considerably more control over the output. +.ad b + +.HP +.ad l +\fB-C\fP|\fB--columns\fP +.br +Display output in columns, the equivalent of vgs(8). +Options listed are the same as options given in vgs(8). +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--foreign\fP +.br +Report/display foreign VGs that would otherwise be skipped. +See lvmsystemid(7) for more information about foreign VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--logonly\fP +.br +Suppress command report and display only log report. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-m\fP|\fB--maps\fP +.br +Display the mapping of physical extents to LVs and logical extents. +.ad b + +.HP +.ad l +\fB--noheadings\fP +.br +Suppress the headings line that is normally the first line of output. +Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--nosuffix\fP +.br +Suppress the suffix on output sizes. Use with --units +(except h and H) if processing the output. +.ad b + +.HP +.ad l +\fB-o\fP|\fB--options\fP \fIString\fP +.br +Comma-separated, ordered list of fields to display in columns. +String arg syntax is: [+|-|#]Field1[,Field2 ...] +The prefix \fB+\fP will append the specified fields to the default fields, +\fB-\fP will remove the specified fields from the default fields, and +\fB#\fP will compact specified fields (removing them when empty for all rows.) +Use \fB-o help\fP to view the list of all available fields. +The -o option can be repeated, providing several lists. +These lists are evaluated from left to right. +Use field name \fBlv_all\fP to view all LV fields, +\fBvg_all\fP all VG fields, +\fBpv_all\fP all PV fields, +\fBpvseg_all\fP all PV segment fields, +\fBseg_all\fP all LV segment fields, and +\fBpvseg_all\fP all PV segment columns. +See the lvm.conf report section for more config options. +See lvmreport(7) for more information about reporting. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB--separator\fP \fIString\fP +.br +String to use to separate each column. Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--shared\fP +.br +Report/display shared VGs that would otherwise be skipped when +lvmlockd is not being used on the host. +See lvmlockd(8) for more information about shared VGs. +.ad b + +.HP +.ad l +\fB-s\fP|\fB--short\fP +.br +Only display the size of the given PVs. +.ad b + +.HP +.ad l +\fB-O\fP|\fB--sort\fP \fIString\fP +.br +Comma-separated ordered list of columns to sort by. Replaces the default +selection. Precede any column with \fB-\fP for a reverse sort on that column. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--unbuffered\fP +.br +Produce output immediately without sorting or aligning the columns properly. +.ad b + +.HP +.ad l +\fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP +.br +All sizes are output in these units: +human-(r)eadable with '<' rounding indicator, +(h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, +(g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. +Capitalise to use multiples of 1000 (S.I.) instead of 1024. +Custom units can be specified, e.g. --units 3M. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvmove.8.des b/man/pvmove.8.des deleted file mode 100644 index c003c5e..0000000 --- a/man/pvmove.8.des +++ /dev/null @@ -1,16 +0,0 @@ -pvmove moves the allocated physical extents (PEs) on a source PV to one or -more destination PVs. You can optionally specify a source LV in which -case only extents used by that LV will be moved to free (or specified) -extents on the destination PV. If no destination PV is specified, the -normal allocation rules for the VG are used. - -If pvmove is interrupted for any reason (e.g. the machine crashes) then -run pvmove again without any PV arguments to restart any operations that -were in progress from the last checkpoint. Alternatively, use the abort -option at any time to abort the operation. The resulting location of LVs -after an abort depends on whether the atomic option was used. - -More than one pvmove can run concurrently if they are moving data from -different source PVs, but additional pvmoves will ignore any LVs already -in the process of being changed, so some data might not get moved. - diff --git a/man/pvmove.8.end b/man/pvmove.8.end deleted file mode 100644 index 906606d..0000000 --- a/man/pvmove.8.end +++ /dev/null @@ -1,93 +0,0 @@ -.SH NOTES - -pvmove works as follows: - -1. A temporary 'pvmove' LV is created to store details of all the data -movements required. - -2. Every LV in the VG is searched for contiguous data that need moving -according to the command line arguments. -For each piece of data found, a new segment is added to the end of the -pvmove LV. -This segment takes the form of a temporary mirror to copy the data -from the original location to a newly allocated location. -The original LV is updated to use the new temporary mirror segment -in the pvmove LV instead of accessing the data directly. - -3. The VG metadata is updated on disk. - -4. The first segment of the pvmove LV is activated and starts to mirror -the first part of the data. Only one segment is mirrored at once as this -is usually more efficient. - -5. A daemon repeatedly checks progress at the specified time interval. -When it detects that the first temporary mirror is in sync, it breaks that -mirror so that only the new location for that data gets used and writes a -checkpoint into the VG metadata on disk. Then it activates the mirror for -the next segment of the pvmove LV. - -6. When there are no more segments left to be mirrored, the temporary LV -is removed and the VG metadata is updated so that the LVs reflect the new -data locations. - -Note that this new process cannot support the original LVM1 -type of on-disk metadata. Metadata can be converted using -\fBvgconvert\fP(8). - -If the \fB\-\-atomic\fP option is used, a slightly different approach is -used for the move. Again, a temporary 'pvmove' LV is created to store the -details of all the data movements required. This temporary LV contains -all the segments of the various LVs that need to be moved. However, in -this case, an identical LV is allocated that contains the same number of -segments and a mirror is created to copy the contents from the first -temporary LV to the second. After a complete copy is made, the temporary -LVs are removed, leaving behind the segments on the destination PV. If an -abort is issued during the move, all LVs being moved will remain on the -source PV. - -.SH EXAMPLES - -Move all physical extents that are used by simple LVs on the specified PV to -free physical extents elsewhere in the VG. -.br -.B pvmove /dev/sdb1 - -Use a specific destination PV when moving physical extents. -.br -.B pvmove /dev/sdb1 /dev/sdc1 - -Move extents belonging to a single LV. -.br -.B pvmove \-n lvol1 /dev/sdb1 /dev/sdc1 - -Rather than moving the contents of an entire device, it is possible to -move a range of physical extents, for example numbers 1000 to 1999 -inclusive on the specified PV. -.br -.B pvmove /dev/sdb1:1000\-1999 - -A range of physical extents to move can be specified as start+length. For -example, starting from PE 1000. (Counting starts from 0, so this refers to the -1001st to the 2000th PE inclusive.) -.br -.B pvmove /dev/sdb1:1000+1000 - -Move a range of physical extents to a specific PV (which must have -sufficient free extents). -.br -.B pvmove /dev/sdb1:1000\-1999 /dev/sdc1 - -Move a range of physical extents to specific new extents on a new PV. -.br -.B pvmove /dev/sdb1:1000\-1999 /dev/sdc1:0\-999 - -If the source and destination are on the same disk, the -\fBanywhere\fP allocation policy is needed. -.br -.B pvmove \-\-alloc anywhere /dev/sdb1:1000\-1999 /dev/sdb1:0\-999 - -The part of a specific LV present within in a range of physical -extents can also be picked out and moved. -.br -.B pvmove \-n lvol1 /dev/sdb1:1000\-1999 /dev/sdc1 - diff --git a/man/pvmove.8_des b/man/pvmove.8_des new file mode 100644 index 0000000..c003c5e --- /dev/null +++ b/man/pvmove.8_des @@ -0,0 +1,16 @@ +pvmove moves the allocated physical extents (PEs) on a source PV to one or +more destination PVs. You can optionally specify a source LV in which +case only extents used by that LV will be moved to free (or specified) +extents on the destination PV. If no destination PV is specified, the +normal allocation rules for the VG are used. + +If pvmove is interrupted for any reason (e.g. the machine crashes) then +run pvmove again without any PV arguments to restart any operations that +were in progress from the last checkpoint. Alternatively, use the abort +option at any time to abort the operation. The resulting location of LVs +after an abort depends on whether the atomic option was used. + +More than one pvmove can run concurrently if they are moving data from +different source PVs, but additional pvmoves will ignore any LVs already +in the process of being changed, so some data might not get moved. + diff --git a/man/pvmove.8_end b/man/pvmove.8_end new file mode 100644 index 0000000..906606d --- /dev/null +++ b/man/pvmove.8_end @@ -0,0 +1,93 @@ +.SH NOTES + +pvmove works as follows: + +1. A temporary 'pvmove' LV is created to store details of all the data +movements required. + +2. Every LV in the VG is searched for contiguous data that need moving +according to the command line arguments. +For each piece of data found, a new segment is added to the end of the +pvmove LV. +This segment takes the form of a temporary mirror to copy the data +from the original location to a newly allocated location. +The original LV is updated to use the new temporary mirror segment +in the pvmove LV instead of accessing the data directly. + +3. The VG metadata is updated on disk. + +4. The first segment of the pvmove LV is activated and starts to mirror +the first part of the data. Only one segment is mirrored at once as this +is usually more efficient. + +5. A daemon repeatedly checks progress at the specified time interval. +When it detects that the first temporary mirror is in sync, it breaks that +mirror so that only the new location for that data gets used and writes a +checkpoint into the VG metadata on disk. Then it activates the mirror for +the next segment of the pvmove LV. + +6. When there are no more segments left to be mirrored, the temporary LV +is removed and the VG metadata is updated so that the LVs reflect the new +data locations. + +Note that this new process cannot support the original LVM1 +type of on-disk metadata. Metadata can be converted using +\fBvgconvert\fP(8). + +If the \fB\-\-atomic\fP option is used, a slightly different approach is +used for the move. Again, a temporary 'pvmove' LV is created to store the +details of all the data movements required. This temporary LV contains +all the segments of the various LVs that need to be moved. However, in +this case, an identical LV is allocated that contains the same number of +segments and a mirror is created to copy the contents from the first +temporary LV to the second. After a complete copy is made, the temporary +LVs are removed, leaving behind the segments on the destination PV. If an +abort is issued during the move, all LVs being moved will remain on the +source PV. + +.SH EXAMPLES + +Move all physical extents that are used by simple LVs on the specified PV to +free physical extents elsewhere in the VG. +.br +.B pvmove /dev/sdb1 + +Use a specific destination PV when moving physical extents. +.br +.B pvmove /dev/sdb1 /dev/sdc1 + +Move extents belonging to a single LV. +.br +.B pvmove \-n lvol1 /dev/sdb1 /dev/sdc1 + +Rather than moving the contents of an entire device, it is possible to +move a range of physical extents, for example numbers 1000 to 1999 +inclusive on the specified PV. +.br +.B pvmove /dev/sdb1:1000\-1999 + +A range of physical extents to move can be specified as start+length. For +example, starting from PE 1000. (Counting starts from 0, so this refers to the +1001st to the 2000th PE inclusive.) +.br +.B pvmove /dev/sdb1:1000+1000 + +Move a range of physical extents to a specific PV (which must have +sufficient free extents). +.br +.B pvmove /dev/sdb1:1000\-1999 /dev/sdc1 + +Move a range of physical extents to specific new extents on a new PV. +.br +.B pvmove /dev/sdb1:1000\-1999 /dev/sdc1:0\-999 + +If the source and destination are on the same disk, the +\fBanywhere\fP allocation policy is needed. +.br +.B pvmove \-\-alloc anywhere /dev/sdb1:1000\-1999 /dev/sdb1:0\-999 + +The part of a specific LV present within in a range of physical +extents can also be picked out and moved. +.br +.B pvmove \-n lvol1 /dev/sdb1:1000\-1999 /dev/sdc1 + diff --git a/man/pvmove.8_pregen b/man/pvmove.8_pregen new file mode 100644 index 0000000..b4ce27e --- /dev/null +++ b/man/pvmove.8_pregen @@ -0,0 +1,551 @@ +.TH PVMOVE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvmove \- Move extents from one physical volume to another +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvmove\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +pvmove moves the allocated physical extents (PEs) on a source PV to one or +more destination PVs. You can optionally specify a source LV in which +case only extents used by that LV will be moved to free (or specified) +extents on the destination PV. If no destination PV is specified, the +normal allocation rules for the VG are used. + +If pvmove is interrupted for any reason (e.g. the machine crashes) then +run pvmove again without any PV arguments to restart any operations that +were in progress from the last checkpoint. Alternatively, use the abort +option at any time to abort the operation. The resulting location of LVs +after an abort depends on whether the atomic option was used. + +More than one pvmove can run concurrently if they are moving data from +different source PVs, but additional pvmoves will ignore any LVs already +in the process of being changed, so some data might not get moved. + + +.P +.SH USAGE +.br +.P +. +Move PV extents. +.br +.P +\fBpvmove\fP \fIPV\fP +.br +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-n\fP|\fB--name\fP \fILV\fP ] +.ad b +.br +.ad l +[ \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP ] +.ad b +.br +.ad l +[ \fB--atomic\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP ... ] +.RE + + +Continue or abort existing pvmove operations. +.br +.P +\fBpvmove\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for command: +. +.RS 4 +.ad l +[ \fB-b\fP|\fB--background\fP ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--interval\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--abort\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--abort\fP +.br +Abort any pvmove operations in progress. If a pvmove was started +with the --atomic option, then all LVs will remain on the source PV. +Otherwise, segments that have been moved will remain on the +destination PV, while unmoved segments will remain on the source PV. +.ad b + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB--atomic\fP +.br +Makes a pvmove operation atomic, ensuring that all affected LVs are +moved to the destination PV, or none are if the operation is aborted. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB-b\fP|\fB--background\fP +.br +If the operation requires polling, this option causes the command to +return before the operation is complete, and polling is done in the +background. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-i\fP|\fB--interval\fP \fINumber\fP +.br +Report progress at regular intervals. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-n\fP|\fB--name\fP \fIString\fP +.br +Move only the extents belonging to the named LV. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH NOTES + +pvmove works as follows: + +1. A temporary 'pvmove' LV is created to store details of all the data +movements required. + +2. Every LV in the VG is searched for contiguous data that need moving +according to the command line arguments. +For each piece of data found, a new segment is added to the end of the +pvmove LV. +This segment takes the form of a temporary mirror to copy the data +from the original location to a newly allocated location. +The original LV is updated to use the new temporary mirror segment +in the pvmove LV instead of accessing the data directly. + +3. The VG metadata is updated on disk. + +4. The first segment of the pvmove LV is activated and starts to mirror +the first part of the data. Only one segment is mirrored at once as this +is usually more efficient. + +5. A daemon repeatedly checks progress at the specified time interval. +When it detects that the first temporary mirror is in sync, it breaks that +mirror so that only the new location for that data gets used and writes a +checkpoint into the VG metadata on disk. Then it activates the mirror for +the next segment of the pvmove LV. + +6. When there are no more segments left to be mirrored, the temporary LV +is removed and the VG metadata is updated so that the LVs reflect the new +data locations. + +Note that this new process cannot support the original LVM1 +type of on-disk metadata. Metadata can be converted using +\fBvgconvert\fP(8). + +If the \fB\-\-atomic\fP option is used, a slightly different approach is +used for the move. Again, a temporary 'pvmove' LV is created to store the +details of all the data movements required. This temporary LV contains +all the segments of the various LVs that need to be moved. However, in +this case, an identical LV is allocated that contains the same number of +segments and a mirror is created to copy the contents from the first +temporary LV to the second. After a complete copy is made, the temporary +LVs are removed, leaving behind the segments on the destination PV. If an +abort is issued during the move, all LVs being moved will remain on the +source PV. + +.SH EXAMPLES + +Move all physical extents that are used by simple LVs on the specified PV to +free physical extents elsewhere in the VG. +.br +.B pvmove /dev/sdb1 + +Use a specific destination PV when moving physical extents. +.br +.B pvmove /dev/sdb1 /dev/sdc1 + +Move extents belonging to a single LV. +.br +.B pvmove \-n lvol1 /dev/sdb1 /dev/sdc1 + +Rather than moving the contents of an entire device, it is possible to +move a range of physical extents, for example numbers 1000 to 1999 +inclusive on the specified PV. +.br +.B pvmove /dev/sdb1:1000\-1999 + +A range of physical extents to move can be specified as start+length. For +example, starting from PE 1000. (Counting starts from 0, so this refers to the +1001st to the 2000th PE inclusive.) +.br +.B pvmove /dev/sdb1:1000+1000 + +Move a range of physical extents to a specific PV (which must have +sufficient free extents). +.br +.B pvmove /dev/sdb1:1000\-1999 /dev/sdc1 + +Move a range of physical extents to specific new extents on a new PV. +.br +.B pvmove /dev/sdb1:1000\-1999 /dev/sdc1:0\-999 + +If the source and destination are on the same disk, the +\fBanywhere\fP allocation policy is needed. +.br +.B pvmove \-\-alloc anywhere /dev/sdb1:1000\-1999 /dev/sdb1:0\-999 + +The part of a specific LV present within in a range of physical +extents can also be picked out and moved. +.br +.B pvmove \-n lvol1 /dev/sdb1:1000\-1999 /dev/sdc1 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvremove.8.des b/man/pvremove.8.des deleted file mode 100644 index cc84148..0000000 --- a/man/pvremove.8.des +++ /dev/null @@ -1,7 +0,0 @@ -pvremove wipes the label on a device so that LVM will no longer recognise -it as a PV. - -A PV cannot be removed from a VG while it is used by an active LV. - -Repeat the force option (\fB-ff\fP) to forcibly remove a PV belonging to -an existing VG. Normally, \fBvgreduce\fP(8) should be used instead. diff --git a/man/pvremove.8_des b/man/pvremove.8_des new file mode 100644 index 0000000..cc84148 --- /dev/null +++ b/man/pvremove.8_des @@ -0,0 +1,7 @@ +pvremove wipes the label on a device so that LVM will no longer recognise +it as a PV. + +A PV cannot be removed from a VG while it is used by an active LV. + +Repeat the force option (\fB-ff\fP) to forcibly remove a PV belonging to +an existing VG. Normally, \fBvgreduce\fP(8) should be used instead. diff --git a/man/pvremove.8_end b/man/pvremove.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/pvremove.8_pregen b/man/pvremove.8_pregen new file mode 100644 index 0000000..18873c1 --- /dev/null +++ b/man/pvremove.8_pregen @@ -0,0 +1,323 @@ +.TH PVREMOVE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvremove \- Remove LVM label(s) from physical volume(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvremove\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +pvremove wipes the label on a device so that LVM will no longer recognise +it as a PV. + +A PV cannot be removed from a VG while it is used by an active LV. + +Repeat the force option (\fB-ff\fP) to forcibly remove a PV belonging to +an existing VG. Normally, \fBvgreduce\fP(8) should be used instead. + +.P +.SH USAGE +.br +.P +. +\fBpvremove\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvresize.8.des b/man/pvresize.8.des deleted file mode 100644 index b3cfe63..0000000 --- a/man/pvresize.8.des +++ /dev/null @@ -1,2 +0,0 @@ -pvresize resizes a PV. The PV may already be in a VG and may have active -LVs allocated on it. diff --git a/man/pvresize.8.end b/man/pvresize.8.end deleted file mode 100644 index 316e408..0000000 --- a/man/pvresize.8.end +++ /dev/null @@ -1,16 +0,0 @@ -.SH NOTES - -pvresize will refuse to shrink a PV if it has allocated extents beyond the -new end. - -.SH EXAMPLES - -Expand a PV after enlarging the partition. -.br -.B pvresize /dev/sda1 - -Shrink a PV prior to shrinking the partition (ensure that the PV size is -appropriate for the intended new partition size). -.br -.B pvresize \-\-setphysicalvolumesize 40G /dev/sda1 - diff --git a/man/pvresize.8_des b/man/pvresize.8_des new file mode 100644 index 0000000..b3cfe63 --- /dev/null +++ b/man/pvresize.8_des @@ -0,0 +1,2 @@ +pvresize resizes a PV. The PV may already be in a VG and may have active +LVs allocated on it. diff --git a/man/pvresize.8_end b/man/pvresize.8_end new file mode 100644 index 0000000..316e408 --- /dev/null +++ b/man/pvresize.8_end @@ -0,0 +1,16 @@ +.SH NOTES + +pvresize will refuse to shrink a PV if it has allocated extents beyond the +new end. + +.SH EXAMPLES + +Expand a PV after enlarging the partition. +.br +.B pvresize /dev/sda1 + +Shrink a PV prior to shrinking the partition (ensure that the PV size is +appropriate for the intended new partition size). +.br +.B pvresize \-\-setphysicalvolumesize 40G /dev/sda1 + diff --git a/man/pvresize.8_pregen b/man/pvresize.8_pregen new file mode 100644 index 0000000..a57abf3 --- /dev/null +++ b/man/pvresize.8_pregen @@ -0,0 +1,334 @@ +.TH PVRESIZE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvresize \- Resize physical volume(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvresize\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +pvresize resizes a PV. The PV may already be in a VG and may have active +LVs allocated on it. + +.P +.SH USAGE +.br +.P +. +\fBpvresize\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB--setphysicalvolumesize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--setphysicalvolumesize\fP \fISize\fP[m|UNIT] +.br +Overrides the automatically detected size of the PV. +Use with care, or prior to reducing the physical size of the device. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH NOTES + +pvresize will refuse to shrink a PV if it has allocated extents beyond the +new end. + +.SH EXAMPLES + +Expand a PV after enlarging the partition. +.br +.B pvresize /dev/sda1 + +Shrink a PV prior to shrinking the partition (ensure that the PV size is +appropriate for the intended new partition size). +.br +.B pvresize \-\-setphysicalvolumesize 40G /dev/sda1 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvs.8.des b/man/pvs.8.des deleted file mode 100644 index 08497ce..0000000 --- a/man/pvs.8.des +++ /dev/null @@ -1 +0,0 @@ -pvs produces formatted output about PVs. diff --git a/man/pvs.8.end b/man/pvs.8.end deleted file mode 100644 index ba36a8b..0000000 --- a/man/pvs.8.end +++ /dev/null @@ -1,11 +0,0 @@ -.SH NOTES -. -The pv_attr bits are: -.IP 1 3 -(d)uplicate, (a)llocatable, (u)sed -.IP 2 3 -e(x)ported -.IP 3 3 -(m)issing - - diff --git a/man/pvs.8_des b/man/pvs.8_des new file mode 100644 index 0000000..08497ce --- /dev/null +++ b/man/pvs.8_des @@ -0,0 +1 @@ +pvs produces formatted output about PVs. diff --git a/man/pvs.8_end b/man/pvs.8_end new file mode 100644 index 0000000..ba36a8b --- /dev/null +++ b/man/pvs.8_end @@ -0,0 +1,11 @@ +.SH NOTES +. +The pv_attr bits are: +.IP 1 3 +(d)uplicate, (a)llocatable, (u)sed +.IP 2 3 +e(x)ported +.IP 3 3 +(m)issing + + diff --git a/man/pvs.8_pregen b/man/pvs.8_pregen new file mode 100644 index 0000000..5df8c4a --- /dev/null +++ b/man/pvs.8_pregen @@ -0,0 +1,656 @@ +.TH PVS 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvs \- Display information about physical volumes +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvs\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +pvs produces formatted output about PVs. + +.P +.SH USAGE +.br +.P +. +\fBpvs\fP +.br +.RS 4 +.ad l +[ \fB-a\fP|\fB--all\fP ] +.ad b +.br +.ad l +[ \fB-o\fP|\fB--options\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-O\fP|\fB--sort\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--segments\fP ] +.ad b +.br +.ad l +[ \fB--aligned\fP ] +.ad b +.br +.ad l +[ \fB--binary\fP ] +.ad b +.br +.ad l +[ \fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP ] +.ad b +.br +.ad l +[ \fB--foreign\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--logonly\fP ] +.ad b +.br +.ad l +[ \fB--nameprefixes\fP ] +.ad b +.br +.ad l +[ \fB--noheadings\fP ] +.ad b +.br +.ad l +[ \fB--nolocking\fP ] +.ad b +.br +.ad l +[ \fB--nosuffix\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--rows\fP ] +.ad b +.br +.ad l +[ \fB--separator\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--shared\fP ] +.ad b +.br +.ad l +[ \fB--trustcache\fP ] +.ad b +.br +.ad l +[ \fB--unbuffered\fP ] +.ad b +.br +.ad l +[ \fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP ] +.ad b +.br +.ad l +[ \fB--unquoted\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIPV\fP|\fITag\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--aligned\fP +.br +Use with --separator to align the output columns +.ad b + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +Show information about devices that have not been initialized +by LVM, i.e. they are not PVs. +.ad b + +.HP +.ad l +\fB--binary\fP +.br +Use binary values "0" or "1" instead of descriptive literal values +for columns that have exactly two valid values to report (not counting +the "unknown" value which denotes that the value could not be determined). +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--foreign\fP +.br +Report/display foreign VGs that would otherwise be skipped. +See lvmsystemid(7) for more information about foreign VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--logonly\fP +.br +Suppress command report and display only log report. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--nameprefixes\fP +.br +Add an "LVM2_" prefix plus the field name to the output. Useful +with --noheadings to produce a list of field=value pairs that can +be used to set environment variables (for example, in udev rules). +.ad b + +.HP +.ad l +\fB--noheadings\fP +.br +Suppress the headings line that is normally the first line of output. +Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--nolocking\fP +.br +Disable locking. +.ad b + +.HP +.ad l +\fB--nosuffix\fP +.br +Suppress the suffix on output sizes. Use with --units +(except h and H) if processing the output. +.ad b + +.HP +.ad l +\fB-o\fP|\fB--options\fP \fIString\fP +.br +Comma-separated, ordered list of fields to display in columns. +String arg syntax is: [+|-|#]Field1[,Field2 ...] +The prefix \fB+\fP will append the specified fields to the default fields, +\fB-\fP will remove the specified fields from the default fields, and +\fB#\fP will compact specified fields (removing them when empty for all rows.) +Use \fB-o help\fP to view the list of all available fields. +The -o option can be repeated, providing several lists. +These lists are evaluated from left to right. +Use field name \fBlv_all\fP to view all LV fields, +\fBvg_all\fP all VG fields, +\fBpv_all\fP all PV fields, +\fBpvseg_all\fP all PV segment fields, +\fBseg_all\fP all LV segment fields, and +\fBpvseg_all\fP all PV segment columns. +See the lvm.conf report section for more config options. +See lvmreport(7) for more information about reporting. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--rows\fP +.br +Output columns as rows. +.ad b + +.HP +.ad l +\fB--segments\fP +.br +Produces one line of output for each contiguous allocation of space on each +PV, showing the start (pvseg_start) and length (pvseg_size) in units of +physical extents. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB--separator\fP \fIString\fP +.br +String to use to separate each column. Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--shared\fP +.br +Report/display shared VGs that would otherwise be skipped when +lvmlockd is not being used on the host. +See lvmlockd(8) for more information about shared VGs. +.ad b + +.HP +.ad l +\fB-O\fP|\fB--sort\fP \fIString\fP +.br +Comma-separated ordered list of columns to sort by. Replaces the default +selection. Precede any column with \fB-\fP for a reverse sort on that column. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--trustcache\fP +.br +Avoids certain device scanning during command processing. Do not use. +.ad b + +.HP +.ad l +\fB--unbuffered\fP +.br +Produce output immediately without sorting or aligning the columns properly. +.ad b + +.HP +.ad l +\fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP +.br +All sizes are output in these units: +human-(r)eadable with '<' rounding indicator, +(h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, +(g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. +Capitalise to use multiples of 1000 (S.I.) instead of 1024. +Custom units can be specified, e.g. --units 3M. +.ad b + +.HP +.ad l +\fB--unquoted\fP +.br +When used with --nameprefixes, output values in the field=value +pairs are not quoted. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH NOTES +. +The pv_attr bits are: +.IP 1 3 +(d)uplicate, (a)llocatable, (u)sed +.IP 2 3 +e(x)ported +.IP 3 3 +(m)issing + + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/pvscan.8.des b/man/pvscan.8.des deleted file mode 100644 index ab8c50c..0000000 --- a/man/pvscan.8.des +++ /dev/null @@ -1,105 +0,0 @@ -pvscan scans all supported LVM block devices in the system for PVs. - -\fBScanning with lvmetad\fP - -pvscan operates differently when used with the -.BR lvmetad (8) -daemon. - -Scanning disks is required to read LVM metadata and identify LVM PVs. -Once read, lvmetad caches the metadata so that LVM commands can read it -without repeatedly scanning disks. This is helpful because scanning disks -is time consuming, and frequent scanning may interfere with the normal -work of the system and disks. - -When lvmetad is not used, LVM commands revert to scanning disks to read -metadata. Any LVM command that needs metadata will scan disks for it; -running the pvscan command is not necessary for the sake of other LVM -commands. - -When lvmetad is used, LVM commands avoid scanning disks by reading -metadata from lvmetad. When new disks appear, they must be scanned so -their metadata can be cached in lvmetad. This is done by the command -pvscan \-\-cache, which scans disks and passes the metadata to lvmetad. - -The pvscan \-\-cache command is typically run automatically by system -services when a new device appears. Users do not generally need to run -this command if the system and lvmetad are running properly. - -Many scripts contain unnecessary pvscan (or vgscan) commands for -historical reasons. To avoid disrupting the system with extraneous disk -scanning, an ordinary pvscan (without \-\-cache) will simply read metadata -from lvmetad like other LVM commands. It does not do anything beyond -displaying the current state of the cache. - -.IP \[bu] 2 -When given specific device name arguments, pvscan \-\-cache will only -read the named devices. - -.IP \[bu] 2 -LVM udev rules and systemd services are used to initiate automatic device -scanning. - -.IP \[bu] 2 -To prevent devices from being scanned by pvscan --cache, add them -to -.BR lvm.conf (5) -.B devices/global_filter. -The devices/filter setting does not -apply to system level scanning. -For more information, see: -.br -.B lvmconfig --withcomments devices/global_filter - -.IP \[bu] 2 -If lvmetad is started or restarted after devices are visible, or -if the global_filter has changed, then all devices must be rescanned -for metadata with the command pvscan \-\-cache. - -.IP \[bu] 2 -lvmetad does not cache older metadata formats, e.g. lvm1, and will -be temporarily disabled if they are seen. - -.IP \[bu] 2 -To notify lvmetad about a device that is no longer present, the major and -minor numbers must be given, not the path. - -.P - -\fBAutomatic activation\fP - -When event-driven system services detect a new LVM device, the first step -is to automatically scan and cache the metadata from the device. This is -done by pvscan \-\-cache. A second step is to automatically activate LVs -that are present on the new device. This auto-activation is done by the -same pvscan \-\-cache command when the option '\-a|\-\-activate ay' is -included. - -Auto-activation of VGs or LVs can be enabled/disabled using: -.br -.BR lvm.conf (5) -.B activation/auto_activation_volume_list - -For more information, see: -.br -.B lvmconfig --withcomments activation/auto_activation_volume_list - -When this setting is undefined, all LVs are auto-activated (when lvm is -fully integrated with the event-driven system services.) - -When a VG or LV is not auto-activated, traditional activation using -vgchange or lvchange -a|--activate is needed. - -.IP \[bu] 2 -pvscan auto-activation can be only done in combination with \-\-cache. - -.IP \[bu] 2 -Auto-activation is designated by the "a" argument in '-a|--activate ay'. -This is meant to distinguish system generated commands from explicit user -commands, although it can be used in any activation command. Whenever it -is used, the auto_activation_volume_list is applied. - -.IP \[bu] 2 -Auto-activation is not yet supported for LVs that are part of partial or -clustered volume groups. - diff --git a/man/pvscan.8_des b/man/pvscan.8_des new file mode 100644 index 0000000..ab8c50c --- /dev/null +++ b/man/pvscan.8_des @@ -0,0 +1,105 @@ +pvscan scans all supported LVM block devices in the system for PVs. + +\fBScanning with lvmetad\fP + +pvscan operates differently when used with the +.BR lvmetad (8) +daemon. + +Scanning disks is required to read LVM metadata and identify LVM PVs. +Once read, lvmetad caches the metadata so that LVM commands can read it +without repeatedly scanning disks. This is helpful because scanning disks +is time consuming, and frequent scanning may interfere with the normal +work of the system and disks. + +When lvmetad is not used, LVM commands revert to scanning disks to read +metadata. Any LVM command that needs metadata will scan disks for it; +running the pvscan command is not necessary for the sake of other LVM +commands. + +When lvmetad is used, LVM commands avoid scanning disks by reading +metadata from lvmetad. When new disks appear, they must be scanned so +their metadata can be cached in lvmetad. This is done by the command +pvscan \-\-cache, which scans disks and passes the metadata to lvmetad. + +The pvscan \-\-cache command is typically run automatically by system +services when a new device appears. Users do not generally need to run +this command if the system and lvmetad are running properly. + +Many scripts contain unnecessary pvscan (or vgscan) commands for +historical reasons. To avoid disrupting the system with extraneous disk +scanning, an ordinary pvscan (without \-\-cache) will simply read metadata +from lvmetad like other LVM commands. It does not do anything beyond +displaying the current state of the cache. + +.IP \[bu] 2 +When given specific device name arguments, pvscan \-\-cache will only +read the named devices. + +.IP \[bu] 2 +LVM udev rules and systemd services are used to initiate automatic device +scanning. + +.IP \[bu] 2 +To prevent devices from being scanned by pvscan --cache, add them +to +.BR lvm.conf (5) +.B devices/global_filter. +The devices/filter setting does not +apply to system level scanning. +For more information, see: +.br +.B lvmconfig --withcomments devices/global_filter + +.IP \[bu] 2 +If lvmetad is started or restarted after devices are visible, or +if the global_filter has changed, then all devices must be rescanned +for metadata with the command pvscan \-\-cache. + +.IP \[bu] 2 +lvmetad does not cache older metadata formats, e.g. lvm1, and will +be temporarily disabled if they are seen. + +.IP \[bu] 2 +To notify lvmetad about a device that is no longer present, the major and +minor numbers must be given, not the path. + +.P + +\fBAutomatic activation\fP + +When event-driven system services detect a new LVM device, the first step +is to automatically scan and cache the metadata from the device. This is +done by pvscan \-\-cache. A second step is to automatically activate LVs +that are present on the new device. This auto-activation is done by the +same pvscan \-\-cache command when the option '\-a|\-\-activate ay' is +included. + +Auto-activation of VGs or LVs can be enabled/disabled using: +.br +.BR lvm.conf (5) +.B activation/auto_activation_volume_list + +For more information, see: +.br +.B lvmconfig --withcomments activation/auto_activation_volume_list + +When this setting is undefined, all LVs are auto-activated (when lvm is +fully integrated with the event-driven system services.) + +When a VG or LV is not auto-activated, traditional activation using +vgchange or lvchange -a|--activate is needed. + +.IP \[bu] 2 +pvscan auto-activation can be only done in combination with \-\-cache. + +.IP \[bu] 2 +Auto-activation is designated by the "a" argument in '-a|--activate ay'. +This is meant to distinguish system generated commands from explicit user +commands, although it can be used in any activation command. Whenever it +is used, the auto_activation_volume_list is applied. + +.IP \[bu] 2 +Auto-activation is not yet supported for LVs that are part of partial or +clustered volume groups. + diff --git a/man/pvscan.8_end b/man/pvscan.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/pvscan.8_pregen b/man/pvscan.8_pregen new file mode 100644 index 0000000..dc64b21 --- /dev/null +++ b/man/pvscan.8_pregen @@ -0,0 +1,542 @@ +.TH PVSCAN 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +pvscan \- List all physical volumes +.P +. +.SH SYNOPSIS +.br +.P +. +\fBpvscan\fP \fIoption_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +pvscan scans all supported LVM block devices in the system for PVs. + +\fBScanning with lvmetad\fP + +pvscan operates differently when used with the +.BR lvmetad (8) +daemon. + +Scanning disks is required to read LVM metadata and identify LVM PVs. +Once read, lvmetad caches the metadata so that LVM commands can read it +without repeatedly scanning disks. This is helpful because scanning disks +is time consuming, and frequent scanning may interfere with the normal +work of the system and disks. + +When lvmetad is not used, LVM commands revert to scanning disks to read +metadata. Any LVM command that needs metadata will scan disks for it; +running the pvscan command is not necessary for the sake of other LVM +commands. + +When lvmetad is used, LVM commands avoid scanning disks by reading +metadata from lvmetad. When new disks appear, they must be scanned so +their metadata can be cached in lvmetad. This is done by the command +pvscan \-\-cache, which scans disks and passes the metadata to lvmetad. + +The pvscan \-\-cache command is typically run automatically by system +services when a new device appears. Users do not generally need to run +this command if the system and lvmetad are running properly. + +Many scripts contain unnecessary pvscan (or vgscan) commands for +historical reasons. To avoid disrupting the system with extraneous disk +scanning, an ordinary pvscan (without \-\-cache) will simply read metadata +from lvmetad like other LVM commands. It does not do anything beyond +displaying the current state of the cache. + +.IP \[bu] 2 +When given specific device name arguments, pvscan \-\-cache will only +read the named devices. + +.IP \[bu] 2 +LVM udev rules and systemd services are used to initiate automatic device +scanning. + +.IP \[bu] 2 +To prevent devices from being scanned by pvscan --cache, add them +to +.BR lvm.conf (5) +.B devices/global_filter. +The devices/filter setting does not +apply to system level scanning. +For more information, see: +.br +.B lvmconfig --withcomments devices/global_filter + +.IP \[bu] 2 +If lvmetad is started or restarted after devices are visible, or +if the global_filter has changed, then all devices must be rescanned +for metadata with the command pvscan \-\-cache. + +.IP \[bu] 2 +lvmetad does not cache older metadata formats, e.g. lvm1, and will +be temporarily disabled if they are seen. + +.IP \[bu] 2 +To notify lvmetad about a device that is no longer present, the major and +minor numbers must be given, not the path. + +.P + +\fBAutomatic activation\fP + +When event-driven system services detect a new LVM device, the first step +is to automatically scan and cache the metadata from the device. This is +done by pvscan \-\-cache. A second step is to automatically activate LVs +that are present on the new device. This auto-activation is done by the +same pvscan \-\-cache command when the option '\-a|\-\-activate ay' is +included. + +Auto-activation of VGs or LVs can be enabled/disabled using: +.br +.BR lvm.conf (5) +.B activation/auto_activation_volume_list + +For more information, see: +.br +.B lvmconfig --withcomments activation/auto_activation_volume_list + +When this setting is undefined, all LVs are auto-activated (when lvm is +fully integrated with the event-driven system services.) + +When a VG or LV is not auto-activated, traditional activation using +vgchange or lvchange -a|--activate is needed. + +.IP \[bu] 2 +pvscan auto-activation can be only done in combination with \-\-cache. + +.IP \[bu] 2 +Auto-activation is designated by the "a" argument in '-a|--activate ay'. +This is meant to distinguish system generated commands from explicit user +commands, although it can be used in any activation command. Whenever it +is used, the auto_activation_volume_list is applied. + +.IP \[bu] 2 +Auto-activation is not yet supported for LVs that are part of partial or +clustered volume groups. + + +.P +.SH USAGE +.br +.P +. +Display PV information. +.br +.P +\fBpvscan\fP +.br +.RS 4 +.ad l +[ \fB-e\fP|\fB--exported\fP ] +.ad b +.br +.ad l +[ \fB-n\fP|\fB--novolumegroup\fP ] +.ad b +.br +.ad l +[ \fB-s\fP|\fB--short\fP ] +.ad b +.br +.ad l +[ \fB-u\fP|\fB--uuid\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Populate the lvmetad cache by scanning PVs. +.br +.P +\fBpvscan\fP \fB--cache\fP +.br +.RS 4 +.ad l +[ \fB-b\fP|\fB--background\fP ] +.ad b +.br +.ad l +[ \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP ] +.ad b +.br +.ad l +[ \fB-j\fP|\fB--major\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--minor\fP \fINumber\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIString\fP|\fIPV\fP ... ] +.RE + + +Common options for command: +. +.RS 4 +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP +.br +.ad b + +.HP +.ad l +\fB-b\fP|\fB--background\fP +.br +If the operation requires polling, this option causes the command to +return before the operation is complete, and polling is done in the +background. +.ad b + +.HP +.ad l +\fB--cache\fP +.br +Scan one or more devices and send the metadata to lvmetad. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-e\fP|\fB--exported\fP +.br +Only show PVs belonging to exported VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-j\fP|\fB--major\fP \fINumber\fP +.br +The major number of a device. +.ad b + +.HP +.ad l +\fB--minor\fP \fINumber\fP +.br +The minor number of a device. +.ad b + +.HP +.ad l +\fB-n\fP|\fB--novolumegroup\fP +.br +Only show PVs not belonging to any VG. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-s\fP|\fB--short\fP +.br +Short listing format. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-u\fP|\fB--uuid\fP +.br +Show UUIDs in addition to device names. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgcfgbackup.8.des b/man/vgcfgbackup.8.des deleted file mode 100644 index 0720e01..0000000 --- a/man/vgcfgbackup.8.des +++ /dev/null @@ -1,16 +0,0 @@ -vgcfgbackup creates back up files containing metadata of VGs. -If no VGs are named, back up files are created for all VGs. -See \fBvgcfgrestore\fP for information on using the back up -files. - -In a default installation, each VG is backed up into a separate file -bearing the name of the VG in the directory \fI#DEFAULT_BACKUP_DIR#\fP. - -To use an alternative back up file, use \fB\-f\fP. In this case, when -backing up multiple VGs, the file name is treated as a template, with %s -replaced by the VG name. - -NB. This DOES NOT back up the data content of LVs. - -It may also be useful to regularly back up the files in -\fI#DEFAULT_SYS_DIR#\fP. diff --git a/man/vgcfgbackup.8_des b/man/vgcfgbackup.8_des new file mode 100644 index 0000000..0720e01 --- /dev/null +++ b/man/vgcfgbackup.8_des @@ -0,0 +1,16 @@ +vgcfgbackup creates back up files containing metadata of VGs. +If no VGs are named, back up files are created for all VGs. +See \fBvgcfgrestore\fP for information on using the back up +files. + +In a default installation, each VG is backed up into a separate file +bearing the name of the VG in the directory \fI#DEFAULT_BACKUP_DIR#\fP. + +To use an alternative back up file, use \fB\-f\fP. In this case, when +backing up multiple VGs, the file name is treated as a template, with %s +replaced by the VG name. + +NB. This DOES NOT back up the data content of LVs. + +It may also be useful to regularly back up the files in +\fI#DEFAULT_SYS_DIR#\fP. diff --git a/man/vgcfgbackup.8_end b/man/vgcfgbackup.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgcfgbackup.8_pregen b/man/vgcfgbackup.8_pregen new file mode 100644 index 0000000..8808540 --- /dev/null +++ b/man/vgcfgbackup.8_pregen @@ -0,0 +1,389 @@ +.TH VGCFGBACKUP 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgcfgbackup \- Backup volume group configuration(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgcfgbackup\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +vgcfgbackup creates back up files containing metadata of VGs. +If no VGs are named, back up files are created for all VGs. +See \fBvgcfgrestore\fP for information on using the back up +files. + +In a default installation, each VG is backed up into a separate file +bearing the name of the VG in the directory \fI/etc/lvm/backup\fP. + +To use an alternative back up file, use \fB\-f\fP. In this case, when +backing up multiple VGs, the file name is treated as a template, with %s +replaced by the VG name. + +NB. This DOES NOT back up the data content of LVs. + +It may also be useful to regularly back up the files in +\fI/etc/lvm\fP. + +.P +.SH USAGE +.br +.P +. +\fBvgcfgbackup\fP +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--file\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB--foreign\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--file\fP \fIString\fP +.br +Write the backup to the named file. +When backing up more than one VG, the file name is +treated as a template, and %s is replaced by the VG name. +.ad b + +.HP +.ad l +\fB--foreign\fP +.br +Report/display foreign VGs that would otherwise be skipped. +See lvmsystemid(7) for more information about foreign VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgcfgrestore.8.des b/man/vgcfgrestore.8.des deleted file mode 100644 index ee3a99e..0000000 --- a/man/vgcfgrestore.8.des +++ /dev/null @@ -1,11 +0,0 @@ -vgcfgrestore restores the metadata of a VG from a text back up file -produced by \fBvgcfgbackup\fP. This writes VG metadata onto the devices -specifed in back up file. - -A back up file can be specified with \fB\-\-file\fP. If no backup file is -specified, the most recent one is used. Use \fB\-\-list\fP for a list of -the available back up and archive files of a VG. - -WARNING: When a VG contains thin pools, changes to thin metadata cannot be -reverted, and data loss may occur if thin metadata has changed. The force -option is required to restore in this case. diff --git a/man/vgcfgrestore.8.end b/man/vgcfgrestore.8.end deleted file mode 100644 index 5ac451d..0000000 --- a/man/vgcfgrestore.8.end +++ /dev/null @@ -1,9 +0,0 @@ -.SH NOTES - -To replace PVs, \fBvgdisplay \-\-partial \-\-verbose\fP will show the -UUIDs and sizes of any PVs that are no longer present. If a PV in the VG -is lost and you wish to substitute another of the same size, use -\fBpvcreate \-\-restorefile filename \-\-uuid uuid\fP (plus additional -arguments as appropriate) to initialise it with the same UUID as the -missing PV. Repeat for all other missing PVs in the VG. Then use -\fBvgcfgrestore \-\-file filename\fP to restore the VG's metadata. diff --git a/man/vgcfgrestore.8_des b/man/vgcfgrestore.8_des new file mode 100644 index 0000000..ee3a99e --- /dev/null +++ b/man/vgcfgrestore.8_des @@ -0,0 +1,11 @@ +vgcfgrestore restores the metadata of a VG from a text back up file +produced by \fBvgcfgbackup\fP. This writes VG metadata onto the devices +specifed in back up file. + +A back up file can be specified with \fB\-\-file\fP. If no backup file is +specified, the most recent one is used. Use \fB\-\-list\fP for a list of +the available back up and archive files of a VG. + +WARNING: When a VG contains thin pools, changes to thin metadata cannot be +reverted, and data loss may occur if thin metadata has changed. The force +option is required to restore in this case. diff --git a/man/vgcfgrestore.8_end b/man/vgcfgrestore.8_end new file mode 100644 index 0000000..5ac451d --- /dev/null +++ b/man/vgcfgrestore.8_end @@ -0,0 +1,9 @@ +.SH NOTES + +To replace PVs, \fBvgdisplay \-\-partial \-\-verbose\fP will show the +UUIDs and sizes of any PVs that are no longer present. If a PV in the VG +is lost and you wish to substitute another of the same size, use +\fBpvcreate \-\-restorefile filename \-\-uuid uuid\fP (plus additional +arguments as appropriate) to initialise it with the same UUID as the +missing PV. Repeat for all other missing PVs in the VG. Then use +\fBvgcfgrestore \-\-file filename\fP to restore the VG's metadata. diff --git a/man/vgcfgrestore.8_pregen b/man/vgcfgrestore.8_pregen new file mode 100644 index 0000000..36da543 --- /dev/null +++ b/man/vgcfgrestore.8_pregen @@ -0,0 +1,473 @@ +.TH VGCFGRESTORE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgcfgrestore \- Restore volume group configuration +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgcfgrestore\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.P +.ad l + \fB--commandprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--config\fP \fIString\fP +.ad b +.br +.ad l + \fB-d\fP|\fB--debug\fP +.ad b +.br +.ad l + \fB--driverloaded\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-f\fP|\fB--file\fP \fIString\fP +.ad b +.br +.ad l + \fB--force\fP +.ad b +.br +.ad l + \fB-h\fP|\fB--help\fP +.ad b +.br +.ad l + \fB-l\fP|\fB--list\fP +.ad b +.br +.ad l + \fB--longhelp\fP +.ad b +.br +.ad l + \fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP +.ad b +.br +.ad l + \fB-q\fP|\fB--quiet\fP +.ad b +.br +.ad l + \fB-t\fP|\fB--test\fP +.ad b +.br +.ad l + \fB-v\fP|\fB--verbose\fP +.ad b +.br +.ad l + \fB--version\fP +.ad b +.br +.ad l + \fB-y\fP|\fB--yes\fP +.ad b + +.P + +.SH DESCRIPTION +vgcfgrestore restores the metadata of a VG from a text back up file +produced by \fBvgcfgbackup\fP. This writes VG metadata onto the devices +specifed in back up file. + +A back up file can be specified with \fB\-\-file\fP. If no backup file is +specified, the most recent one is used. Use \fB\-\-list\fP for a list of +the available back up and archive files of a VG. + +WARNING: When a VG contains thin pools, changes to thin metadata cannot be +reverted, and data loss may occur if thin metadata has changed. The force +option is required to restore in this case. + +.P +.SH USAGE +.br +.P +. +Restore VG metadata from last backup. +.br +.P +\fBvgcfgrestore\fP \fIVG\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Restore VG metadata from specified file. +.br +.P +\fBvgcfgrestore\fP \fB-f\fP|\fB--file\fP \fIString\fP \fIVG\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +List all VG metadata backups. +.br +.P +\fBvgcfgrestore\fP \fB-l\fP|\fB--list\fP \fIVG\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +List one VG metadata backup file. +.br +.P +\fBvgcfgrestore\fP \fB-l\fP|\fB--list\fP \fB-f\fP|\fB--file\fP \fIString\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP ] +.RE + +-- + +.br + +Common options for command: +. +.RS 4 +.ad l +[ \fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP ] +.ad b +.br +.ad l +[ \fB--force\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--file\fP \fIString\fP +.br +Read metadata backup from the named file. +Usually this file was created by vgcfgbackup. +.ad b + +.HP +.ad l +\fB--force\fP ... +.br +Force metadata restore even with thin pool LVs. +Use with extreme caution. Most changes to thin metadata +cannot be reverted. +You may lose data if you restore metadata that does not match the +thin pool kernel metadata precisely. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--list\fP +.br +List metadata backup and archive files pertaining to the VG. +May be used with --file. Does not restore the VG. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP +.br +Specifies the type of on-disk metadata to use. +\fBlvm2\fP (or just \fB2\fP) is the current, standard format. +\fBlvm1\fP (or just \fB1\fP) is a historical format that +can be used for accessing old data. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH NOTES + +To replace PVs, \fBvgdisplay \-\-partial \-\-verbose\fP will show the +UUIDs and sizes of any PVs that are no longer present. If a PV in the VG +is lost and you wish to substitute another of the same size, use +\fBpvcreate \-\-restorefile filename \-\-uuid uuid\fP (plus additional +arguments as appropriate) to initialise it with the same UUID as the +missing PV. Repeat for all other missing PVs in the VG. Then use +\fBvgcfgrestore \-\-file filename\fP to restore the VG's metadata. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgchange.8.des b/man/vgchange.8.des deleted file mode 100644 index 6b873d8..0000000 --- a/man/vgchange.8.des +++ /dev/null @@ -1,2 +0,0 @@ -vgchange changes VG attributes, changes LV activation in the kernel, and -includes other utilities for VG maintenance. diff --git a/man/vgchange.8.end b/man/vgchange.8.end deleted file mode 100644 index a11bdd1..0000000 --- a/man/vgchange.8.end +++ /dev/null @@ -1,16 +0,0 @@ -.SH NOTES - -If vgchange recognizes COW snapshot LVs that were dropped because they ran -out of space, it displays a message informing the administrator that the -snapshots should be removed. - -.SH EXAMPLES - -Activate all LVs in all VGs on all existing devices. -.br -.B vgchange \-a y - -Change the maximum number of LVs for an inactive VG. -.br -.B vgchange \-l 128 vg00 - diff --git a/man/vgchange.8_des b/man/vgchange.8_des new file mode 100644 index 0000000..6b873d8 --- /dev/null +++ b/man/vgchange.8_des @@ -0,0 +1,2 @@ +vgchange changes VG attributes, changes LV activation in the kernel, and +includes other utilities for VG maintenance. diff --git a/man/vgchange.8_end b/man/vgchange.8_end new file mode 100644 index 0000000..a11bdd1 --- /dev/null +++ b/man/vgchange.8_end @@ -0,0 +1,16 @@ +.SH NOTES + +If vgchange recognizes COW snapshot LVs that were dropped because they ran +out of space, it displays a message informing the administrator that the +snapshots should be removed. + +.SH EXAMPLES + +Activate all LVs in all VGs on all existing devices. +.br +.B vgchange \-a y + +Change the maximum number of LVs for an inactive VG. +.br +.B vgchange \-l 128 vg00 + diff --git a/man/vgchange.8_pregen b/man/vgchange.8_pregen new file mode 100644 index 0000000..1494f4e --- /dev/null +++ b/man/vgchange.8_pregen @@ -0,0 +1,1151 @@ +.TH VGCHANGE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgchange \- Change volume group attributes +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgchange\fP \fIoption_args\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.P +.ad l + \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP +.ad b +.br +.ad l + \fB--activationmode\fP \fBpartial\fP|\fBdegraded\fP|\fBcomplete\fP +.ad b +.br +.ad l + \fB--addtag\fP \fITag\fP +.ad b +.br +.ad l + \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.ad b +.br +.ad l + \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-c\fP|\fB--clustered\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--commandprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--config\fP \fIString\fP +.ad b +.br +.ad l + \fB-d\fP|\fB--debug\fP +.ad b +.br +.ad l + \fB--deltag\fP \fITag\fP +.ad b +.br +.ad l + \fB--detachprofile\fP +.ad b +.br +.ad l + \fB--driverloaded\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-f\fP|\fB--force\fP +.ad b +.br +.ad l + \fB-h\fP|\fB--help\fP +.ad b +.br +.ad l + \fB-K\fP|\fB--ignoreactivationskip\fP +.ad b +.br +.ad l + \fB--ignorelockingfailure\fP +.ad b +.br +.ad l + \fB--ignoremonitoring\fP +.ad b +.br +.ad l + \fB--ignoreskippedcluster\fP +.ad b +.br +.ad l + \fB--lockopt\fP \fIString\fP +.ad b +.br +.ad l + \fB--lockstart\fP +.ad b +.br +.ad l + \fB--lockstop\fP +.ad b +.br +.ad l + \fB--locktype\fP \fBsanlock\fP|\fBdlm\fP|\fBnone\fP +.ad b +.br +.ad l + \fB-l\fP|\fB--logicalvolume\fP \fINumber\fP +.ad b +.br +.ad l + \fB--longhelp\fP +.ad b +.br +.ad l + \fB-p\fP|\fB--maxphysicalvolumes\fP \fINumber\fP +.ad b +.br +.ad l + \fB--metadataprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--monitor\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--noudevsync\fP +.ad b +.br +.ad l + \fB-P\fP|\fB--partial\fP +.ad b +.br +.ad l + \fB-s\fP|\fB--physicalextentsize\fP \fISize\fP[m|UNIT] +.ad b +.br +.ad l + \fB--poll\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP +.ad b +.br +.ad l + \fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP +.ad b +.br +.ad l + \fB-q\fP|\fB--quiet\fP +.ad b +.br +.ad l + \fB--refresh\fP +.ad b +.br +.ad l + \fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.ad b +.br +.ad l + \fB-x\fP|\fB--resizeable\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-S\fP|\fB--select\fP \fIString\fP +.ad b +.br +.ad l + \fB--sysinit\fP +.ad b +.br +.ad l + \fB--systemid\fP \fIString\fP +.ad b +.br +.ad l + \fB-t\fP|\fB--test\fP +.ad b +.br +.ad l + \fB-u\fP|\fB--uuid\fP +.ad b +.br +.ad l + \fB-v\fP|\fB--verbose\fP +.ad b +.br +.ad l + \fB--version\fP +.ad b +.br +.ad l + \fB--[vg]metadatacopies\fP \fBall\fP|\fBunmanaged\fP|\fINumber\fP +.ad b +.br +.ad l + \fB-y\fP|\fB--yes\fP +.ad b + +.P + +.SH DESCRIPTION +vgchange changes VG attributes, changes LV activation in the kernel, and +includes other utilities for VG maintenance. + +.P +.SH USAGE +.br +.P +. +Change a general VG attribute. +.br +For options listed in parentheses, any one is +.br +required, after which the others are optional. +.br +.P +\fBvgchange\fP +.RS 4 +( \fB-l\fP|\fB--logicalvolume\fP \fINumber\fP, +.ad b +.br +.ad l + \fB-p\fP|\fB--maxphysicalvolumes\fP \fINumber\fP, +.ad b +.br +.ad l + \fB-u\fP|\fB--uuid\fP, +.ad b +.br +.ad l + \fB-c\fP|\fB--clustered\fP \fBy\fP|\fBn\fP, +.ad b +.br +.ad l + \fB-s\fP|\fB--physicalextentsize\fP \fISize\fP[m|UNIT], +.ad b +.br +.ad l + \fB-x\fP|\fB--resizeable\fP \fBy\fP|\fBn\fP, +.ad b +.br +.ad l + \fB--addtag\fP \fITag\fP, +.ad b +.br +.ad l + \fB--deltag\fP \fITag\fP, +.ad b +.br +.ad l + \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP, +.ad b +.br +.ad l + \fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP, +.ad b +.br +.ad l + \fB--[vg]metadatacopies\fP \fBall\fP|\fBunmanaged\fP|\fINumber\fP, +.ad b +.br +.ad l + \fB--systemid\fP \fIString\fP, +.ad b +.br +.ad l + \fB--locktype\fP \fBsanlock\fP|\fBdlm\fP|\fBnone\fP, +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP, +.ad b +.br +.ad l + \fB--detachprofile\fP, +.ad b +.br +.ad l + \fB--metadataprofile\fP \fIString\fP ) +.RE +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP|\fISelect\fP ... ] +.RE + +-- + +.br + +Start or stop monitoring LVs from dmeventd. +.br +.P +\fBvgchange\fP \fB--monitor\fP \fBy\fP|\fBn\fP +.br +.RS 4 +.ad l +[ \fB--sysinit\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--poll\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP|\fISelect\fP ... ] +.RE + +-- + +.br + +Start or stop processing LV conversions. +.br +.P +\fBvgchange\fP \fB--poll\fP \fBy\fP|\fBn\fP +.br +.RS 4 +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP|\fISelect\fP ... ] +.RE + +-- + +.br + +Activate or deactivate LVs. +.br +.P +\fBvgchange\fP \fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP +.br +.RS 4 +.ad l +[ \fB-K\fP|\fB--ignoreactivationskip\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB--activationmode\fP \fBpartial\fP|\fBdegraded\fP|\fBcomplete\fP ] +.ad b +.br +.ad l +[ \fB--sysinit\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--monitor\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--poll\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP|\fISelect\fP ... ] +.RE + +-- + +.br + +Reactivate LVs using the latest metadata. +.br +.P +\fBvgchange\fP \fB--refresh\fP +.br +.RS 4 +.ad l +[ \fB--sysinit\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--monitor\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--poll\fP \fBy\fP|\fBn\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP|\fISelect\fP ... ] +.RE + +-- + +.br + +Start the lockspace of a shared VG in lvmlockd. +.br +.P +\fBvgchange\fP \fB--lockstart\fP +.br +.RS 4 +.ad l +[ \fB--lockopt\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP|\fISelect\fP ... ] +.RE + +-- + +.br + +Stop the lockspace of a shared VG in lvmlockd. +.br +.P +\fBvgchange\fP \fB--lockstop\fP +.br +.RS 4 +.ad l +[ \fB--lockopt\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP|\fISelect\fP ... ] +.RE + +-- + +.br + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--ignoremonitoring\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-a\fP|\fB--activate\fP \fBy\fP|\fBn\fP|\fBay\fP +.br +Change the active state of LVs. +An active LV can be used through a block device, +allowing data on the LV to be accessed. +\fBy\fP makes LVs active, or available. +\fBn\fP 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. +\fBay\fP specifies autoactivation, in which case an LV is activated +only if it matches an item in lvm.conf activation/auto_activation_volume_list. +If the list is not set, all LVs are considered to match, and if +if the list is set but empty, no LVs match. +Autoactivation should be used during system boot to make it possible +to select which LVs should be automatically activated by the system. +See lvmlockd(8) for more information about activation options \fBey\fP and \fBsy\fP for shared VGs. +See clvmd(8) for more information about activation options \fBey\fP, \fBsy\fP, \fBly\fP and \fBln\fP for clustered VGs. +.ad b + +.HP +.ad l +\fB--activationmode\fP \fBpartial\fP|\fBdegraded\fP|\fBcomplete\fP +.br +Determines if LV activation is allowed when PVs are missing, +e.g. because of a device failure. +\fBcomplete\fP only allows LVs with no missing PVs to be activated, +and is the most restrictive mode. +\fBdegraded\fP allows RAID LVs with missing PVs to be activated. +(This does not include the "mirror" type, see "raid1" instead.) +\fBpartial\fP allows any LV with missing PVs to be activated, and +should only be used for recovery or repair. +For default, see lvm.conf/activation_mode. +See \fBlvmraid\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--addtag\fP \fITag\fP +.br +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. +.ad b + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB-c\fP|\fB--clustered\fP \fBy\fP|\fBn\fP +.br +Change the clustered property of a VG using clvmd. +See clvmd(8) for more information about clustered VGs. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--deltag\fP \fITag\fP +.br +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. +.ad b + +.HP +.ad l +\fB--detachprofile\fP +.br +Detaches a metadata profile from a VG or LV. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-K\fP|\fB--ignoreactivationskip\fP +.br +Ignore the "activation skip" LV flag during activation +to allow LVs with the flag set to be activated. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoremonitoring\fP +.br +Do not interact with dmeventd unless --monitor is specified. +Do not use this if dmeventd is already monitoring a device. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--lockopt\fP \fIString\fP +.br +Used to pass options for special cases to lvmlockd. +See lvmlockd(8) for more information. +.ad b + +.HP +.ad l +\fB--lockstart\fP +.br +Start the lockspace of a shared VG in lvmlockd. +lvmlockd locks becomes available for the VG, allowing LVM to use the VG. +See lvmlockd(8) for more information. +.ad b + +.HP +.ad l +\fB--lockstop\fP +.br +Stop the lockspace of a shared VG in lvmlockd. +lvmlockd locks become unavailable for the VG, preventing LVM from using the VG. +See lvmlockd(8) for more information. +.ad b + +.HP +.ad l +\fB--locktype\fP \fBsanlock\fP|\fBdlm\fP|\fBnone\fP +.br +Change the VG lock type to or from a shared lock type used with lvmlockd. +See lvmlockd(8) for more information. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--logicalvolume\fP \fINumber\fP +.br +Sets the maximum number of LVs allowed in a VG. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-p\fP|\fB--maxphysicalvolumes\fP \fINumber\fP +.br +Sets the maximum number of PVs that can belong to the VG. +The value 0 removes any limitation. +For large numbers of PVs, also see options --pvmetadatacopies, +and --vgmetadatacopies for improving performance. +.ad b + +.HP +.ad l +\fB--metadataprofile\fP \fIString\fP +.br +The metadata profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--monitor\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB-s\fP|\fB--physicalextentsize\fP \fISize\fP[m|UNIT] +.br +Sets the physical extent size of PVs in the VG. +The value must be either a power of 2 of at least 1 sector +(where the sector size is the largest sector size of the PVs +currently used in the VG), or at least 128KiB. +Once this value has been set, it is difficult to change +without recreating the VG, unless no extents need moving. +Before increasing the physical extent size, you might need to use lvresize, +pvresize and/or pvmove so that everything fits. For example, every +contiguous range of extents used in a LV must start and end on an extent boundary. +.ad b + +.HP +.ad l +\fB--poll\fP \fBy\fP|\fBn\fP +.br +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. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP +.br +The number of metadata areas to set aside on a PV for storing VG metadata. +When 2, one copy of the VG metadata is stored at the front of the PV +and a second copy is stored at the end. +When 1, one copy of the VG metadata is stored at the front of the PV +(starting in the 5th sector). +When 0, no copies of the VG metadata are stored on the given PV. +This may be useful in VGs containing many PVs (this places limitations +on the ability to use vgsplit later.) +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--refresh\fP +.br +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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-x\fP|\fB--resizeable\fP \fBy\fP|\fBn\fP +.br +Enables or disables the addition or removal of PVs to/from a VG +(by vgextend/vgreduce). +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB--sysinit\fP +.br +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. +When used in conjunction with lvmetad enabled and running, +vgchange/lvchange skip autoactivation, and defer to pvscan autoactivation. +.ad b + +.HP +.ad l +\fB--systemid\fP \fIString\fP +.br +Changes the system ID of the VG. Using this option requires caution +because the VG may become foreign to the host running the command, +leaving the host unable to access it. +See lvmsystemid(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-u\fP|\fB--uuid\fP +.br +Generate new random UUID for specified VGs. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB--[vg]metadatacopies\fP \fBall\fP|\fBunmanaged\fP|\fINumber\fP +.br +Number of copies of the VG metadata that are kept. +VG metadata is kept in VG metadata areas on PVs in the VG, +i.e. reserved space at the start and/or end of the PVs. +Keeping a copy of the VG metadata on every PV can reduce performance +in VGs containing a large number of PVs. +When this number is set to a non-zero value, LVM will automatically +choose PVs on which to store metadata, using the metadataignore flags +on PVs to achieve the specified number. +The number can also be replaced with special string values: +\fBunmanaged\fP causes LVM to not automatically manage the PV +metadataignore flags. +\fBall\fP causes LVM to first clear the metadataignore flags on +all PVs, and then to become unmanaged. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fISelect\fP +.br +Select indicates that a required positional parameter can +be omitted if the \fB--select\fP option is used. +No arg appears in this position. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH NOTES + +If vgchange recognizes COW snapshot LVs that were dropped because they ran +out of space, it displays a message informing the administrator that the +snapshots should be removed. + +.SH EXAMPLES + +Activate all LVs in all VGs on all existing devices. +.br +.B vgchange \-a y + +Change the maximum number of LVs for an inactive VG. +.br +.B vgchange \-l 128 vg00 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgck.8.des b/man/vgck.8.des deleted file mode 100644 index 24e1dbe..0000000 --- a/man/vgck.8.des +++ /dev/null @@ -1 +0,0 @@ -vgck checks LVM metadata for consistency. diff --git a/man/vgck.8_des b/man/vgck.8_des new file mode 100644 index 0000000..24e1dbe --- /dev/null +++ b/man/vgck.8_des @@ -0,0 +1 @@ +vgck checks LVM metadata for consistency. diff --git a/man/vgck.8_end b/man/vgck.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgck.8_pregen b/man/vgck.8_pregen new file mode 100644 index 0000000..fa01362 --- /dev/null +++ b/man/vgck.8_pregen @@ -0,0 +1,310 @@ +.TH VGCK 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgck \- Check the consistency of volume group(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgck\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +vgck checks LVM metadata for consistency. + +.P +.SH USAGE +.br +.P +. +\fBvgck\fP +.br +.RS 4 +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgconvert.8.des b/man/vgconvert.8.des deleted file mode 100644 index 47bc0cc..0000000 --- a/man/vgconvert.8.des +++ /dev/null @@ -1,7 +0,0 @@ -vgconvert converts VG metadata from one format to another. The new -metadata format must be able to fit into the space provided by the old -format. - -Because the LVM1 format should no longer be used, this command is no -longer needed in general. - diff --git a/man/vgconvert.8_des b/man/vgconvert.8_des new file mode 100644 index 0000000..47bc0cc --- /dev/null +++ b/man/vgconvert.8_des @@ -0,0 +1,7 @@ +vgconvert converts VG metadata from one format to another. The new +metadata format must be able to fit into the space provided by the old +format. + +Because the LVM1 format should no longer be used, this command is no +longer needed in general. + diff --git a/man/vgconvert.8_end b/man/vgconvert.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgconvert.8_pregen b/man/vgconvert.8_pregen new file mode 100644 index 0000000..4f89b9e --- /dev/null +++ b/man/vgconvert.8_pregen @@ -0,0 +1,394 @@ +.TH VGCONVERT 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgconvert \- Change volume group metadata format +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgconvert\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgconvert converts VG metadata from one format to another. The new +metadata format must be able to fit into the space provided by the old +format. + +Because the LVM1 format should no longer be used, this command is no +longer needed in general. + + +.P +.SH USAGE +.br +.P +. +\fBvgconvert\fP \fIVG\fP ... +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP ] +.ad b +.br +.ad l +[ \fB--labelsector\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--bootloaderareasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +.ad l +[ \fB--metadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--bootloaderareasize\fP \fISize\fP[m|UNIT] +.br +Create a separate bootloader area of specified size besides PV's data +area. The bootloader area is an area of reserved space on the PV from +which LVM will not allocate any extents and it's kept untouched. This is +primarily aimed for use with bootloaders to embed their own data or metadata. +The start of the bootloader area is always aligned, see also --dataalignment +and --dataalignmentoffset. The bootloader area size may eventually +end up increased due to the alignment, but it's never less than the +size that is requested. To see the bootloader area start and size of +an existing PV use pvs -o +pv_ba_start,pv_ba_size. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--labelsector\fP \fINumber\fP +.br +By default the PV is labelled with an LVM2 identifier in its second +sector (sector 1). This lets you use a different sector near the +start of the disk (between 0 and 3 inclusive - see LABEL_SCAN_SECTORS +in the source). Use with care. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--metadatasize\fP \fISize\fP[m|UNIT] +.br +The approximate amount of space used for each VG metadata area. +The size may be rounded. +.ad b + +.HP +.ad l +\fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP +.br +Specifies the type of on-disk metadata to use. +\fBlvm2\fP (or just \fB2\fP) is the current, standard format. +\fBlvm1\fP (or just \fB1\fP) is a historical format that +can be used for accessing old data. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP +.br +The number of metadata areas to set aside on a PV for storing VG metadata. +When 2, one copy of the VG metadata is stored at the front of the PV +and a second copy is stored at the end. +When 1, one copy of the VG metadata is stored at the front of the PV +(starting in the 5th sector). +When 0, no copies of the VG metadata are stored on the given PV. +This may be useful in VGs containing many PVs (this places limitations +on the ability to use vgsplit later.) +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgcreate.8.des b/man/vgcreate.8.des deleted file mode 100644 index a2d7161..0000000 --- a/man/vgcreate.8.des +++ /dev/null @@ -1,4 +0,0 @@ -vgcreate creates a new VG on block devices. If the devices were not -previously intialized as PVs with \fBpvcreate\fP(8), vgcreate will -inititialize them, making them PVs. The pvcreate options for initializing -devices are also available with vgcreate. diff --git a/man/vgcreate.8.end b/man/vgcreate.8.end deleted file mode 100644 index 66bcfbb..0000000 --- a/man/vgcreate.8.end +++ /dev/null @@ -1,6 +0,0 @@ -.SH EXAMPLES - -Create a VG with two PVs, using the default physical extent size. -.br -.B vgcreate myvg /dev/sdk1 /dev/sdl1 - diff --git a/man/vgcreate.8_des b/man/vgcreate.8_des new file mode 100644 index 0000000..a2d7161 --- /dev/null +++ b/man/vgcreate.8_des @@ -0,0 +1,4 @@ +vgcreate creates a new VG on block devices. If the devices were not +previously intialized as PVs with \fBpvcreate\fP(8), vgcreate will +inititialize them, making them PVs. The pvcreate options for initializing +devices are also available with vgcreate. diff --git a/man/vgcreate.8_end b/man/vgcreate.8_end new file mode 100644 index 0000000..66bcfbb --- /dev/null +++ b/man/vgcreate.8_end @@ -0,0 +1,6 @@ +.SH EXAMPLES + +Create a VG with two PVs, using the default physical extent size. +.br +.B vgcreate myvg /dev/sdk1 /dev/sdl1 + diff --git a/man/vgcreate.8_pregen b/man/vgcreate.8_pregen new file mode 100644 index 0000000..5c73312 --- /dev/null +++ b/man/vgcreate.8_pregen @@ -0,0 +1,626 @@ +.TH VGCREATE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgcreate \- Create a volume group +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgcreate\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgcreate creates a new VG on block devices. If the devices were not +previously intialized as PVs with \fBpvcreate\fP(8), vgcreate will +inititialize them, making them PVs. The pvcreate options for initializing +devices are also available with vgcreate. + +.P +.SH USAGE +.br +.P +. +\fBvgcreate\fP \fIVG\fP\fI_new\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--clustered\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-l\fP|\fB--maxlogicalvolumes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-p\fP|\fB--maxphysicalvolumes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP ] +.ad b +.br +.ad l +[ \fB-s\fP|\fB--physicalextentsize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--addtag\fP \fITag\fP ] +.ad b +.br +.ad l +[ \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP ] +.ad b +.br +.ad l +[ \fB--metadataprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--labelsector\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--metadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +.ad l +[ \fB--[vg]metadatacopies\fP \fBall\fP|\fBunmanaged\fP|\fINumber\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--dataalignment\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--dataalignmentoffset\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--shared\fP ] +.ad b +.br +.ad l +[ \fB--systemid\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--locktype\fP \fBsanlock\fP|\fBdlm\fP|\fBnone\fP ] +.ad b +.br +.ad l +[ \fB--lockopt\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--addtag\fP \fITag\fP +.br +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. +.ad b + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB-c\fP|\fB--clustered\fP \fBy\fP|\fBn\fP +.br +Create a clustered VG using clvmd if LVM is compiled with cluster support. +This allows multiple hosts to share a VG on shared devices. +clvmd and a lock manager must be configured and running. +(A clustered VG using clvmd is different from a shared VG using lvmlockd.) +See clvmd(8) for more information about clustered VGs. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--dataalignment\fP \fISize\fP[k|UNIT] +.br +Align the start of the data to a multiple of this number. +Also specify an appropriate Physical Extent size when creating a VG. +To see the location of the first Physical Extent of an existing PV, +use pvs -o +pe_start. In addition, it may be shifted by an alignment offset. +See lvm.conf/data_alignment_offset_detection and --dataalignmentoffset. +.ad b + +.HP +.ad l +\fB--dataalignmentoffset\fP \fISize\fP[k|UNIT] +.br +Shift the start of the data area by this additional offset. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--labelsector\fP \fINumber\fP +.br +By default the PV is labelled with an LVM2 identifier in its second +sector (sector 1). This lets you use a different sector near the +start of the disk (between 0 and 3 inclusive - see LABEL_SCAN_SECTORS +in the source). Use with care. +.ad b + +.HP +.ad l +\fB--lockopt\fP \fIString\fP +.br +Used to pass options for special cases to lvmlockd. +See lvmlockd(8) for more information. +.ad b + +.HP +.ad l +\fB--locktype\fP \fBsanlock\fP|\fBdlm\fP|\fBnone\fP +.br +Specify the VG lock type directly in place of using --shared. +See lvmlockd(8) for more information. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--maxlogicalvolumes\fP \fINumber\fP +.br +Sets the maximum number of LVs allowed in a VG. +.ad b + +.HP +.ad l +\fB-p\fP|\fB--maxphysicalvolumes\fP \fINumber\fP +.br +Sets the maximum number of PVs that can belong to the VG. +The value 0 removes any limitation. +For large numbers of PVs, also see options --pvmetadatacopies, +and --vgmetadatacopies for improving performance. +.ad b + +.HP +.ad l +\fB--metadataprofile\fP \fIString\fP +.br +The metadata profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--metadatasize\fP \fISize\fP[m|UNIT] +.br +The approximate amount of space used for each VG metadata area. +The size may be rounded. +.ad b + +.HP +.ad l +\fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP +.br +Specifies the type of on-disk metadata to use. +\fBlvm2\fP (or just \fB2\fP) is the current, standard format. +\fBlvm1\fP (or just \fB1\fP) is a historical format that +can be used for accessing old data. +.ad b + +.HP +.ad l +\fB-s\fP|\fB--physicalextentsize\fP \fISize\fP[m|UNIT] +.br +Sets the physical extent size of PVs in the VG. +The value must be either a power of 2 of at least 1 sector +(where the sector size is the largest sector size of the PVs +currently used in the VG), or at least 128KiB. +Once this value has been set, it is difficult to change +without recreating the VG, unless no extents need moving. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP +.br +The number of metadata areas to set aside on a PV for storing VG metadata. +When 2, one copy of the VG metadata is stored at the front of the PV +and a second copy is stored at the end. +When 1, one copy of the VG metadata is stored at the front of the PV +(starting in the 5th sector). +When 0, no copies of the VG metadata are stored on the given PV. +This may be useful in VGs containing many PVs (this places limitations +on the ability to use vgsplit later.) +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--shared\fP +.br +Create a shared VG using lvmlockd if LVM is compiled with lockd support. +lvmlockd will select lock type sanlock or dlm depending on which lock +manager is running. This allows multiple hosts to share a VG on shared +devices. lvmlockd and a lock manager must be configured and running. +(A shared VG using lvmlockd is different from a clustered VG using clvmd.) +See lvmlockd(8) for more information about shared VGs. +.ad b + +.HP +.ad l +\fB--systemid\fP \fIString\fP +.br +Specifies the system ID that will be given to the new VG, overriding the +system ID of the host running the command. A VG is normally created +without this option, in which case the new VG is given the system ID of +the host creating it. Using this option requires caution because the +system ID of the new VG may not match the system ID of the host running +the command, leaving the VG inaccessible to the host. +See lvmsystemid(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB--[vg]metadatacopies\fP \fBall\fP|\fBunmanaged\fP|\fINumber\fP +.br +Number of copies of the VG metadata that are kept. +VG metadata is kept in VG metadata areas on PVs in the VG, +i.e. reserved space at the start and/or end of the PVs. +Keeping a copy of the VG metadata on every PV can reduce performance +in VGs containing a large number of PVs. +When this number is set to a non-zero value, LVM will automatically +choose PVs on which to store metadata, using the metadataignore flags +on PVs to achieve the specified number. +The number can also be replaced with special string values: +\fBunmanaged\fP causes LVM to not automatically manage the PV +metadataignore flags. +\fBall\fP causes LVM to first clear the metadataignore flags on +all PVs, and then to become unmanaged. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b + +.HP +.ad l +\fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.br +Controls if the first 4 sectors (2048 bytes) of the device are wiped. +The default is to wipe these sectors unless either or both of +--restorefile or --uuid are specified. +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Create a VG with two PVs, using the default physical extent size. +.br +.B vgcreate myvg /dev/sdk1 /dev/sdl1 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgdisplay.8.des b/man/vgdisplay.8.des deleted file mode 100644 index c42f821..0000000 --- a/man/vgdisplay.8.des +++ /dev/null @@ -1,4 +0,0 @@ -vgdisplay shows the attributes of VGs, and the associated PVs and LVs. - -\fBvgs\fP(8) is a preferred alternative that shows the same information -and more, using a more compact and configurable output format. diff --git a/man/vgdisplay.8_des b/man/vgdisplay.8_des new file mode 100644 index 0000000..c42f821 --- /dev/null +++ b/man/vgdisplay.8_des @@ -0,0 +1,4 @@ +vgdisplay shows the attributes of VGs, and the associated PVs and LVs. + +\fBvgs\fP(8) is a preferred alternative that shows the same information +and more, using a more compact and configurable output format. diff --git a/man/vgdisplay.8_end b/man/vgdisplay.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgdisplay.8_pregen b/man/vgdisplay.8_pregen new file mode 100644 index 0000000..352a521 --- /dev/null +++ b/man/vgdisplay.8_pregen @@ -0,0 +1,606 @@ +.TH VGDISPLAY 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgdisplay \- Display volume group information +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgdisplay\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +vgdisplay shows the attributes of VGs, and the associated PVs and LVs. + +\fBvgs\fP(8) is a preferred alternative that shows the same information +and more, using a more compact and configurable output format. + +.P +.SH USAGE +.br +.P +. +\fBvgdisplay\fP +.br +.RS 4 +.ad l +[ \fB-A\fP|\fB--activevolumegroups\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--colon\fP ] +.ad b +.br +.ad l +[ \fB-C\fP|\fB--columns\fP ] +.ad b +.br +.ad l +[ \fB-o\fP|\fB--options\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-s\fP|\fB--short\fP ] +.ad b +.br +.ad l +[ \fB-O\fP|\fB--sort\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--aligned\fP ] +.ad b +.br +.ad l +[ \fB--binary\fP ] +.ad b +.br +.ad l +[ \fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP ] +.ad b +.br +.ad l +[ \fB--foreign\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--logonly\fP ] +.ad b +.br +.ad l +[ \fB--noheadings\fP ] +.ad b +.br +.ad l +[ \fB--nosuffix\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--shared\fP ] +.ad b +.br +.ad l +[ \fB--separator\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--unbuffered\fP ] +.ad b +.br +.ad l +[ \fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-A\fP|\fB--activevolumegroups\fP +.br +Only select active VGs. The VG is considered active +if at least one of its LVs is active. +.ad b + +.HP +.ad l +\fB--aligned\fP +.br +Use with --separator to align the output columns +.ad b + +.HP +.ad l +\fB--binary\fP +.br +Use binary values "0" or "1" instead of descriptive literal values +for columns that have exactly two valid values to report (not counting +the "unknown" value which denotes that the value could not be determined). +.ad b + +.HP +.ad l +\fB-c\fP|\fB--colon\fP +.br +Generate colon separated output for easier parsing in scripts or programs. +Also see vgs(8) which provides considerably more control over the output. +.ad b + +.HP +.ad l +\fB-C\fP|\fB--columns\fP +.br +Display output in columns, the equivalent of vgs(8). +Options listed are the same as options given in vgs(8). +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--foreign\fP +.br +Report/display foreign VGs that would otherwise be skipped. +See lvmsystemid(7) for more information about foreign VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--logonly\fP +.br +Suppress command report and display only log report. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--noheadings\fP +.br +Suppress the headings line that is normally the first line of output. +Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--nosuffix\fP +.br +Suppress the suffix on output sizes. Use with --units +(except h and H) if processing the output. +.ad b + +.HP +.ad l +\fB-o\fP|\fB--options\fP \fIString\fP +.br +Comma-separated, ordered list of fields to display in columns. +String arg syntax is: [+|-|#]Field1[,Field2 ...] +The prefix \fB+\fP will append the specified fields to the default fields, +\fB-\fP will remove the specified fields from the default fields, and +\fB#\fP will compact specified fields (removing them when empty for all rows.) +Use \fB-o help\fP to view the list of all available fields. +The -o option can be repeated, providing several lists. +These lists are evaluated from left to right. +Use field name \fBlv_all\fP to view all LV fields, +\fBvg_all\fP all VG fields, +\fBpv_all\fP all PV fields, +\fBpvseg_all\fP all PV segment fields, +\fBseg_all\fP all LV segment fields, and +\fBpvseg_all\fP all PV segment columns. +See the lvm.conf report section for more config options. +See lvmreport(7) for more information about reporting. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB--separator\fP \fIString\fP +.br +String to use to separate each column. Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--shared\fP +.br +Report/display shared VGs that would otherwise be skipped when +lvmlockd is not being used on the host. +See lvmlockd(8) for more information about shared VGs. +.ad b + +.HP +.ad l +\fB-s\fP|\fB--short\fP +.br +Give a short listing showing the existence of VGs. +.ad b + +.HP +.ad l +\fB-O\fP|\fB--sort\fP \fIString\fP +.br +Comma-separated ordered list of columns to sort by. Replaces the default +selection. Precede any column with \fB-\fP for a reverse sort on that column. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--unbuffered\fP +.br +Produce output immediately without sorting or aligning the columns properly. +.ad b + +.HP +.ad l +\fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP +.br +All sizes are output in these units: +human-(r)eadable with '<' rounding indicator, +(h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, +(g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. +Capitalise to use multiples of 1000 (S.I.) instead of 1024. +Custom units can be specified, e.g. --units 3M. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgexport.8.des b/man/vgexport.8.des deleted file mode 100644 index f9fa49c..0000000 --- a/man/vgexport.8.des +++ /dev/null @@ -1,8 +0,0 @@ -vgexport makes inactive VGs unknown to the system. In this state, all the -PVs in the VG can be moved to a different system, from which -\fBvgimport\fP can then be run. - -Most LVM tools ignore exported VGs. - -vgexport clears the VG system ID, and vgimport sets the VG system ID to -match the host running vgimport (if the host has a system ID). diff --git a/man/vgexport.8_des b/man/vgexport.8_des new file mode 100644 index 0000000..f9fa49c --- /dev/null +++ b/man/vgexport.8_des @@ -0,0 +1,8 @@ +vgexport makes inactive VGs unknown to the system. In this state, all the +PVs in the VG can be moved to a different system, from which +\fBvgimport\fP can then be run. + +Most LVM tools ignore exported VGs. + +vgexport clears the VG system ID, and vgimport sets the VG system ID to +match the host running vgimport (if the host has a system ID). diff --git a/man/vgexport.8_end b/man/vgexport.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgexport.8_pregen b/man/vgexport.8_pregen new file mode 100644 index 0000000..0551c26 --- /dev/null +++ b/man/vgexport.8_pregen @@ -0,0 +1,363 @@ +.TH VGEXPORT 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgexport \- Unregister volume group(s) from the system +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgexport\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgexport makes inactive VGs unknown to the system. In this state, all the +PVs in the VG can be moved to a different system, from which +\fBvgimport\fP can then be run. + +Most LVM tools ignore exported VGs. + +vgexport clears the VG system ID, and vgimport sets the VG system ID to +match the host running vgimport (if the host has a system ID). + +.P +.SH USAGE +.br +.P +. +Export specified VGs. +.br +.P +\fBvgexport\fP \fIVG\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Export all VGs. +.br +.P +\fBvgexport\fP \fB-a\fP|\fB--all\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for command: +. +.RS 4 +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fISelect\fP +.br +Select indicates that a required positional parameter can +be omitted if the \fB--select\fP option is used. +No arg appears in this position. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgextend.8.des b/man/vgextend.8.des deleted file mode 100644 index 85fe6fc..0000000 --- a/man/vgextend.8.des +++ /dev/null @@ -1,11 +0,0 @@ -vgextend adds one or more PVs to a VG. This increases the space available -for LVs in the VG. - -Also, PVs that have gone missing and then returned, e.g. due to a -transient device failure, can be added back to the VG without -re-initializing them (see \-\-restoremissing). - -If the specified PVs have not yet been initialized with pvcreate, vgextend -will initialize them. In this case pvcreate options can be used, e.g. -\-\-labelsector, \-\-metadatasize, \-\-metadataignore, -\-\-pvmetadatacopies, \-\-dataalignment, \-\-dataalignmentoffset. diff --git a/man/vgextend.8.end b/man/vgextend.8.end deleted file mode 100644 index e50fcce..0000000 --- a/man/vgextend.8.end +++ /dev/null @@ -1,6 +0,0 @@ -.SH EXAMPLES - -Add two PVs to a VG. -.br -.B vgextend vg00 /dev/sda4 /dev/sdn1 - diff --git a/man/vgextend.8_des b/man/vgextend.8_des new file mode 100644 index 0000000..85fe6fc --- /dev/null +++ b/man/vgextend.8_des @@ -0,0 +1,11 @@ +vgextend adds one or more PVs to a VG. This increases the space available +for LVs in the VG. + +Also, PVs that have gone missing and then returned, e.g. due to a +transient device failure, can be added back to the VG without +re-initializing them (see \-\-restoremissing). + +If the specified PVs have not yet been initialized with pvcreate, vgextend +will initialize them. In this case pvcreate options can be used, e.g. +\-\-labelsector, \-\-metadatasize, \-\-metadataignore, +\-\-pvmetadatacopies, \-\-dataalignment, \-\-dataalignmentoffset. diff --git a/man/vgextend.8_end b/man/vgextend.8_end new file mode 100644 index 0000000..e50fcce --- /dev/null +++ b/man/vgextend.8_end @@ -0,0 +1,6 @@ +.SH EXAMPLES + +Add two PVs to a VG. +.br +.B vgextend vg00 /dev/sda4 /dev/sdn1 + diff --git a/man/vgextend.8_pregen b/man/vgextend.8_pregen new file mode 100644 index 0000000..42ef268 --- /dev/null +++ b/man/vgextend.8_pregen @@ -0,0 +1,473 @@ +.TH VGEXTEND 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgextend \- Add physical volumes to a volume group +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgextend\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgextend adds one or more PVs to a VG. This increases the space available +for LVs in the VG. + +Also, PVs that have gone missing and then returned, e.g. due to a +transient device failure, can be added back to the VG without +re-initializing them (see \-\-restoremissing). + +If the specified PVs have not yet been initialized with pvcreate, vgextend +will initialize them. In this case pvcreate options can be used, e.g. +\-\-labelsector, \-\-metadatasize, \-\-metadataignore, +\-\-pvmetadatacopies, \-\-dataalignment, \-\-dataalignmentoffset. + +.P +.SH USAGE +.br +.P +. +\fBvgextend\fP \fIVG\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP ] +.ad b +.br +.ad l +[ \fB--labelsector\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB--metadatasize\fP \fISize\fP[m|UNIT] ] +.ad b +.br +.ad l +[ \fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP ] +.ad b +.br +.ad l +[ \fB--metadataignore\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--dataalignment\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--dataalignmentoffset\fP \fISize\fP[k|UNIT] ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--restoremissing\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--dataalignment\fP \fISize\fP[k|UNIT] +.br +Align the start of the data to a multiple of this number. +Also specify an appropriate Physical Extent size when creating a VG. +To see the location of the first Physical Extent of an existing PV, +use pvs -o +pe_start. In addition, it may be shifted by an alignment offset. +See lvm.conf/data_alignment_offset_detection and --dataalignmentoffset. +.ad b + +.HP +.ad l +\fB--dataalignmentoffset\fP \fISize\fP[k|UNIT] +.br +Shift the start of the data area by this additional offset. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--labelsector\fP \fINumber\fP +.br +By default the PV is labelled with an LVM2 identifier in its second +sector (sector 1). This lets you use a different sector near the +start of the disk (between 0 and 3 inclusive - see LABEL_SCAN_SECTORS +in the source). Use with care. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--metadataignore\fP \fBy\fP|\fBn\fP +.br +Specifies the metadataignore property of a PV. +If yes, metadata areas on the PV are ignored, and lvm will +not store metadata in the metadata areas of the PV. +If no, lvm will store metadata on the PV. +.ad b + +.HP +.ad l +\fB--metadatasize\fP \fISize\fP[m|UNIT] +.br +The approximate amount of space used for each VG metadata area. +The size may be rounded. +.ad b + +.HP +.ad l +\fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP +.br +Specifies the type of on-disk metadata to use. +\fBlvm2\fP (or just \fB2\fP) is the current, standard format. +\fBlvm1\fP (or just \fB1\fP) is a historical format that +can be used for accessing old data. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB--pvmetadatacopies\fP \fB0\fP|\fB1\fP|\fB2\fP +.br +The number of metadata areas to set aside on a PV for storing VG metadata. +When 2, one copy of the VG metadata is stored at the front of the PV +and a second copy is stored at the end. +When 1, one copy of the VG metadata is stored at the front of the PV +(starting in the 5th sector). +When 0, no copies of the VG metadata are stored on the given PV. +This may be useful in VGs containing many PVs (this places limitations +on the ability to use vgsplit later.) +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--restoremissing\fP +.br +Add a PV back into a VG after the PV was missing and then returned, +e.g. due to a transient failure. The PV is not reinitialized. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b + +.HP +.ad l +\fB-Z\fP|\fB--zero\fP \fBy\fP|\fBn\fP +.br +Controls if the first 4 sectors (2048 bytes) of the device are wiped. +The default is to wipe these sectors unless either or both of +--restorefile or --uuid are specified. +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Add two PVs to a VG. +.br +.B vgextend vg00 /dev/sda4 /dev/sdn1 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgimport.8.des b/man/vgimport.8.des deleted file mode 100644 index 91196b6..0000000 --- a/man/vgimport.8.des +++ /dev/null @@ -1,5 +0,0 @@ -vgimport makes exported VGs known to the system again, perhaps after -moving the PVs from a different system. - -vgexport clears the VG system ID, and vgimport sets the VG system ID to -match the host running vgimport (if the host has a system ID). diff --git a/man/vgimport.8_des b/man/vgimport.8_des new file mode 100644 index 0000000..91196b6 --- /dev/null +++ b/man/vgimport.8_des @@ -0,0 +1,5 @@ +vgimport makes exported VGs known to the system again, perhaps after +moving the PVs from a different system. + +vgexport clears the VG system ID, and vgimport sets the VG system ID to +match the host running vgimport (if the host has a system ID). diff --git a/man/vgimport.8_end b/man/vgimport.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgimport.8_pregen b/man/vgimport.8_pregen new file mode 100644 index 0000000..e71436f --- /dev/null +++ b/man/vgimport.8_pregen @@ -0,0 +1,372 @@ +.TH VGIMPORT 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgimport \- Register exported volume group with system +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgimport\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgimport makes exported VGs known to the system again, perhaps after +moving the PVs from a different system. + +vgexport clears the VG system ID, and vgimport sets the VG system ID to +match the host running vgimport (if the host has a system ID). + +.P +.SH USAGE +.br +.P +. +Import specified VGs. +.br +.P +\fBvgimport\fP \fIVG\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Import all VGs. +.br +.P +\fBvgimport\fP \fB-a\fP|\fB--all\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for command: +. +.RS 4 +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fISelect\fP +.br +Select indicates that a required positional parameter can +be omitted if the \fB--select\fP option is used. +No arg appears in this position. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgimportclone.8.des b/man/vgimportclone.8.des deleted file mode 100644 index a5002da..0000000 --- a/man/vgimportclone.8.des +++ /dev/null @@ -1,6 +0,0 @@ -vgimportclone imports a VG from duplicated PVs, e.g. created by a hardware -snapshot of existing PVs. - -A duplicated VG cannot used until it is made to coexist with the original -VG. vgimportclone renames the VG associated with the specified PVs and -changes the associated VG and PV UUIDs. diff --git a/man/vgimportclone.8.end b/man/vgimportclone.8.end deleted file mode 100644 index 83394b5..0000000 --- a/man/vgimportclone.8.end +++ /dev/null @@ -1,9 +0,0 @@ -.SH EXAMPLES - -An original VG "vg00" has PVs "/dev/sda" and "/dev/sdb". -The corresponding PVs from a hardware snapshot are "/dev/sdc" and "/dev/sdd". -Rename the VG associated with "/dev/sdc" and "/dev/sdd" from "vg00" to "vg00_snap" -(and change associated UUIDs). -.br -.B vgimportclone \-\-basevgname vg00_snap /dev/sdc /dev/sdd - diff --git a/man/vgimportclone.8_des b/man/vgimportclone.8_des new file mode 100644 index 0000000..a5002da --- /dev/null +++ b/man/vgimportclone.8_des @@ -0,0 +1,6 @@ +vgimportclone imports a VG from duplicated PVs, e.g. created by a hardware +snapshot of existing PVs. + +A duplicated VG cannot used until it is made to coexist with the original +VG. vgimportclone renames the VG associated with the specified PVs and +changes the associated VG and PV UUIDs. diff --git a/man/vgimportclone.8_end b/man/vgimportclone.8_end new file mode 100644 index 0000000..83394b5 --- /dev/null +++ b/man/vgimportclone.8_end @@ -0,0 +1,9 @@ +.SH EXAMPLES + +An original VG "vg00" has PVs "/dev/sda" and "/dev/sdb". +The corresponding PVs from a hardware snapshot are "/dev/sdc" and "/dev/sdd". +Rename the VG associated with "/dev/sdc" and "/dev/sdd" from "vg00" to "vg00_snap" +(and change associated UUIDs). +.br +.B vgimportclone \-\-basevgname vg00_snap /dev/sdc /dev/sdd + diff --git a/man/vgimportclone.8_pregen b/man/vgimportclone.8_pregen new file mode 100644 index 0000000..280e2a8 --- /dev/null +++ b/man/vgimportclone.8_pregen @@ -0,0 +1,330 @@ +.TH VGIMPORTCLONE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgimportclone \- Import a VG from cloned PVs +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgimportclone\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgimportclone imports a VG from duplicated PVs, e.g. created by a hardware +snapshot of existing PVs. + +A duplicated VG cannot used until it is made to coexist with the original +VG. vgimportclone renames the VG associated with the specified PVs and +changes the associated VG and PV UUIDs. + +.P +.SH USAGE +.br +.P +. +\fBvgimportclone\fP \fIPV\fP ... +.br +.RS 4 +.ad l +[ \fB-n\fP|\fB--basevgname\fP \fIVG\fP ] +.ad b +.br +.ad l +[ \fB-i\fP|\fB--import\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-n\fP|\fB--basevgname\fP \fIString\fP +.br +By default the snapshot VG will be renamed to the original name plus a +numeric suffix to avoid duplicate naming (e.g. 'test_vg' would be renamed +to 'test_vg1'). This option will override the base VG name that is +used for all VG renames. If a VG already exists with the specified name +a numeric suffix will be added (like the previous example) to make it unique. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-i\fP|\fB--import\fP +.br +Import exported VGs. Otherwise VGs that have been exported +will not be changed (nor will their associated PVs). +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +An original VG "vg00" has PVs "/dev/sda" and "/dev/sdb". +The corresponding PVs from a hardware snapshot are "/dev/sdc" and "/dev/sdd". +Rename the VG associated with "/dev/sdc" and "/dev/sdd" from "vg00" to "vg00_snap" +(and change associated UUIDs). +.br +.B vgimportclone \-\-basevgname vg00_snap /dev/sdc /dev/sdd + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgmerge.8.des b/man/vgmerge.8.des deleted file mode 100644 index ff7c177..0000000 --- a/man/vgmerge.8.des +++ /dev/null @@ -1,3 +0,0 @@ -vgmerge merges two existing VGs. The inactive source VG is merged into the -destination VG if physical extent sizes are equal and PV and LV summaries -of both VGs fit into the destination VG's limits. diff --git a/man/vgmerge.8.end b/man/vgmerge.8.end deleted file mode 100644 index 9787c6a..0000000 --- a/man/vgmerge.8.end +++ /dev/null @@ -1,7 +0,0 @@ -.SH EXAMPLES - -Merge an inactive VG named "vg00" into the active or inactive VG named -"databases", giving verbose runtime information. -.br -.B vgmerge \-v databases vg00 - diff --git a/man/vgmerge.8_des b/man/vgmerge.8_des new file mode 100644 index 0000000..ff7c177 --- /dev/null +++ b/man/vgmerge.8_des @@ -0,0 +1,3 @@ +vgmerge merges two existing VGs. The inactive source VG is merged into the +destination VG if physical extent sizes are equal and PV and LV summaries +of both VGs fit into the destination VG's limits. diff --git a/man/vgmerge.8_end b/man/vgmerge.8_end new file mode 100644 index 0000000..9787c6a --- /dev/null +++ b/man/vgmerge.8_end @@ -0,0 +1,7 @@ +.SH EXAMPLES + +Merge an inactive VG named "vg00" into the active or inactive VG named +"databases", giving verbose runtime information. +.br +.B vgmerge \-v databases vg00 + diff --git a/man/vgmerge.8_pregen b/man/vgmerge.8_pregen new file mode 100644 index 0000000..ffa9929 --- /dev/null +++ b/man/vgmerge.8_pregen @@ -0,0 +1,315 @@ +.TH VGMERGE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgmerge \- Merge volume groups +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgmerge\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgmerge merges two existing VGs. The inactive source VG is merged into the +destination VG if physical extent sizes are equal and PV and LV summaries +of both VGs fit into the destination VG's limits. + +.P +.SH USAGE +.br +.P +. +\fBvgmerge\fP \fIVG\fP \fIVG\fP +.br +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-l\fP|\fB--list\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--list\fP +.br +Display merged destination VG like vgdisplay -v. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Merge an inactive VG named "vg00" into the active or inactive VG named +"databases", giving verbose runtime information. +.br +.B vgmerge \-v databases vg00 + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgmknodes.8.des b/man/vgmknodes.8.des deleted file mode 100644 index a93d629..0000000 --- a/man/vgmknodes.8.des +++ /dev/null @@ -1,5 +0,0 @@ -vgmknodes checks the LVM device nodes in /dev that are needed for active -LVs and creates any that are missing and removes unused ones. - -This command should not usually be needed if all the system components are -interoperating correctly. diff --git a/man/vgmknodes.8_des b/man/vgmknodes.8_des new file mode 100644 index 0000000..a93d629 --- /dev/null +++ b/man/vgmknodes.8_des @@ -0,0 +1,5 @@ +vgmknodes checks the LVM device nodes in /dev that are needed for active +LVs and creates any that are missing and removes unused ones. + +This command should not usually be needed if all the system components are +interoperating correctly. diff --git a/man/vgmknodes.8_end b/man/vgmknodes.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgmknodes.8_pregen b/man/vgmknodes.8_pregen new file mode 100644 index 0000000..6f785b2 --- /dev/null +++ b/man/vgmknodes.8_pregen @@ -0,0 +1,346 @@ +.TH VGMKNODES 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgmknodes \- Create the special files for volume group devices in /dev +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgmknodes\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +vgmknodes checks the LVM device nodes in /dev that are needed for active +LVs and creates any that are missing and removes unused ones. + +This command should not usually be needed if all the system components are +interoperating correctly. + +.P +.SH USAGE +.br +.P +. +\fBvgmknodes\fP +.br +.RS 4 +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--refresh\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fILV\fP|\fITag\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--refresh\fP +.br +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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fILV\fP +.br +Logical Volume name. See \fBlvm\fP(8) for valid names. +An LV positional arg generally includes the VG name and LV name, e.g. VG/LV. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgreduce.8.des b/man/vgreduce.8.des deleted file mode 100644 index 1bcdaf9..0000000 --- a/man/vgreduce.8.des +++ /dev/null @@ -1 +0,0 @@ -vgreduce removes one or more unused PVs from a VG. diff --git a/man/vgreduce.8_des b/man/vgreduce.8_des new file mode 100644 index 0000000..1bcdaf9 --- /dev/null +++ b/man/vgreduce.8_des @@ -0,0 +1 @@ +vgreduce removes one or more unused PVs from a VG. diff --git a/man/vgreduce.8_end b/man/vgreduce.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgreduce.8_pregen b/man/vgreduce.8_pregen new file mode 100644 index 0000000..548188b --- /dev/null +++ b/man/vgreduce.8_pregen @@ -0,0 +1,483 @@ +.TH VGREDUCE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgreduce \- Remove physical volume(s) from a volume group +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgreduce\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.P +.ad l + \fB-a\fP|\fB--all\fP +.ad b +.br +.ad l + \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB--commandprofile\fP \fIString\fP +.ad b +.br +.ad l + \fB--config\fP \fIString\fP +.ad b +.br +.ad l + \fB-d\fP|\fB--debug\fP +.ad b +.br +.ad l + \fB--driverloaded\fP \fBy\fP|\fBn\fP +.ad b +.br +.ad l + \fB-f\fP|\fB--force\fP +.ad b +.br +.ad l + \fB-h\fP|\fB--help\fP +.ad b +.br +.ad l + \fB--longhelp\fP +.ad b +.br +.ad l + \fB--mirrorsonly\fP +.ad b +.br +.ad l + \fB--profile\fP \fIString\fP +.ad b +.br +.ad l + \fB-q\fP|\fB--quiet\fP +.ad b +.br +.ad l + \fB--removemissing\fP +.ad b +.br +.ad l + \fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.ad b +.br +.ad l + \fB-t\fP|\fB--test\fP +.ad b +.br +.ad l + \fB-v\fP|\fB--verbose\fP +.ad b +.br +.ad l + \fB--version\fP +.ad b +.br +.ad l + \fB-y\fP|\fB--yes\fP +.ad b + +.P + +.SH DESCRIPTION +vgreduce removes one or more unused PVs from a VG. + +.P +.SH USAGE +.br +.P +. +Remove a PV from a VG. +.br +.P +\fBvgreduce\fP \fIVG\fP \fIPV\fP ... +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Remove all unused PVs from a VG. +.br +.P +\fBvgreduce\fP \fB-a\fP|\fB--all\fP \fIVG\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Remove all missing PVs from a VG. +.br +.P +\fBvgreduce\fP \fB--removemissing\fP \fIVG\fP +.br +.RS 4 +.ad l +[ \fB--mirrorsonly\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + +-- + +.br + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +Removes all empty PVs if none are named on the command line. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--mirrorsonly\fP +.br +Only remove missing PVs from mirror LVs. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--removemissing\fP +.br +Removes all missing PVs from the VG, if there are no LVs allocated +on them. This resumes normal operation of the VG (new LVs may again +be created, changed and so on). +If this is not possible because LVs are referencing the missing PVs, +this option can be combined with --force to have the command remove +any partial LVs. In this case, any LVs and dependent snapshots that +were partly on the missing disks are removed completely, including +those parts on disks that are still present. +If LVs spanned several disks, including ones that are lost, salvaging +some data first may be possible by activating LVs in partial mode. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgremove.8.des b/man/vgremove.8.des deleted file mode 100644 index 6414c73..0000000 --- a/man/vgremove.8.des +++ /dev/null @@ -1,9 +0,0 @@ -vgremove removes one or more VGs. If LVs exist in the VG, a prompt is used -to confirm LV removal. - -If one or more PVs in the VG are lost, consider -\fBvgreduce \-\-removemissing\fP to make the VG -metadata consistent again. - -Repeat the force option (\fB-ff\fP) to forcibly remove LVs in the VG -without confirmation. diff --git a/man/vgremove.8_des b/man/vgremove.8_des new file mode 100644 index 0000000..6414c73 --- /dev/null +++ b/man/vgremove.8_des @@ -0,0 +1,9 @@ +vgremove removes one or more VGs. If LVs exist in the VG, a prompt is used +to confirm LV removal. + +If one or more PVs in the VG are lost, consider +\fBvgreduce \-\-removemissing\fP to make the VG +metadata consistent again. + +Repeat the force option (\fB-ff\fP) to forcibly remove LVs in the VG +without confirmation. diff --git a/man/vgremove.8_end b/man/vgremove.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgremove.8_pregen b/man/vgremove.8_pregen new file mode 100644 index 0000000..ab1aa90 --- /dev/null +++ b/man/vgremove.8_pregen @@ -0,0 +1,364 @@ +.TH VGREMOVE 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgremove \- Remove volume group(s) +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgremove\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgremove removes one or more VGs. If LVs exist in the VG, a prompt is used +to confirm LV removal. + +If one or more PVs in the VG are lost, consider +\fBvgreduce \-\-removemissing\fP to make the VG +metadata consistent again. + +Repeat the force option (\fB-ff\fP) to forcibly remove LVs in the VG +without confirmation. + +.P +.SH USAGE +.br +.P +. +\fBvgremove\fP \fIVG\fP|\fITag\fP|\fISelect\fP ... +.br +.RS 4 +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--noudevsync\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--noudevsync\fP +.br +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. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fISelect\fP +.br +Select indicates that a required positional parameter can +be omitted if the \fB--select\fP option is used. +No arg appears in this position. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgrename.8.des b/man/vgrename.8.des deleted file mode 100644 index 2384b6b..0000000 --- a/man/vgrename.8.des +++ /dev/null @@ -1,9 +0,0 @@ -vgrename renames a VG. - -All VGs visible to a system need to have different names, otherwise many -LVM commands will refuse to run or give warning messages. VGs with the -same name can occur when disks are moved between machines, or filters are -changed. If a newly connected disk has a VG with the same name as the VG -containing the root filesystem, the machine may not boot correctly. When -two VGs have the same name, the VG UUID can be used in place of the source -VG name. diff --git a/man/vgrename.8.end b/man/vgrename.8.end deleted file mode 100644 index 98eeb53..0000000 --- a/man/vgrename.8.end +++ /dev/null @@ -1,10 +0,0 @@ -.SH EXAMPLES - -Rename VG "vg02" to "myvg": -.br -.B vgrename "vg02" "myvg" - -Rename the VG with the specified UUID to "myvg". -.br -.B vgrename Zvlifi\-Ep3t\-e0Ng\-U42h\-o0ye\-KHu1\-nl7Ns4 myvg - diff --git a/man/vgrename.8_des b/man/vgrename.8_des new file mode 100644 index 0000000..2384b6b --- /dev/null +++ b/man/vgrename.8_des @@ -0,0 +1,9 @@ +vgrename renames a VG. + +All VGs visible to a system need to have different names, otherwise many +LVM commands will refuse to run or give warning messages. VGs with the +same name can occur when disks are moved between machines, or filters are +changed. If a newly connected disk has a VG with the same name as the VG +containing the root filesystem, the machine may not boot correctly. When +two VGs have the same name, the VG UUID can be used in place of the source +VG name. diff --git a/man/vgrename.8_end b/man/vgrename.8_end new file mode 100644 index 0000000..98eeb53 --- /dev/null +++ b/man/vgrename.8_end @@ -0,0 +1,10 @@ +.SH EXAMPLES + +Rename VG "vg02" to "myvg": +.br +.B vgrename "vg02" "myvg" + +Rename the VG with the specified UUID to "myvg". +.br +.B vgrename Zvlifi\-Ep3t\-e0Ng\-U42h\-o0ye\-KHu1\-nl7Ns4 myvg + diff --git a/man/vgrename.8_pregen b/man/vgrename.8_pregen new file mode 100644 index 0000000..a9055d0 --- /dev/null +++ b/man/vgrename.8_pregen @@ -0,0 +1,361 @@ +.TH VGRENAME 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgrename \- Rename a volume group +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgrename\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgrename renames a VG. + +All VGs visible to a system need to have different names, otherwise many +LVM commands will refuse to run or give warning messages. VGs with the +same name can occur when disks are moved between machines, or filters are +changed. If a newly connected disk has a VG with the same name as the VG +containing the root filesystem, the machine may not boot correctly. When +two VGs have the same name, the VG UUID can be used in place of the source +VG name. + +.P +.SH USAGE +.br +.P +. +Rename a VG. +.br +.P +\fBvgrename\fP \fIVG\fP \fIVG\fP\fI_new\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Rename a VG by specifying the VG UUID. +.br +.P +\fBvgrename\fP \fIString\fP \fIVG\fP\fI_new\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-f\fP|\fB--force\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-f\fP|\fB--force\fP ... +.br +Override various checks, confirmations and protections. +Use with extreme caution. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH EXAMPLES + +Rename VG "vg02" to "myvg": +.br +.B vgrename "vg02" "myvg" + +Rename the VG with the specified UUID to "myvg". +.br +.B vgrename Zvlifi\-Ep3t\-e0Ng\-U42h\-o0ye\-KHu1\-nl7Ns4 myvg + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgs.8.des b/man/vgs.8.des deleted file mode 100644 index 15bdb97..0000000 --- a/man/vgs.8.des +++ /dev/null @@ -1 +0,0 @@ -vgs produces formatted output about VGs. diff --git a/man/vgs.8.end b/man/vgs.8.end deleted file mode 100644 index b8cda26..0000000 --- a/man/vgs.8.end +++ /dev/null @@ -1,17 +0,0 @@ -.SH NOTES -. -The vg_attr bits are: -.IP 1 3 -Permissions: (w)riteable, (r)ead-only -.IP 2 3 -Resi(z)eable -.IP 3 3 -E(x)ported -.IP 4 3 -(p)artial: one or more physical volumes belonging to the volume group -are missing from the system -.IP 5 3 -Allocation policy: (c)ontiguous, c(l)ing, (n)ormal, (a)nywhere -.IP 6 3 -(c)lustered, (s)hared - diff --git a/man/vgs.8_des b/man/vgs.8_des new file mode 100644 index 0000000..15bdb97 --- /dev/null +++ b/man/vgs.8_des @@ -0,0 +1 @@ +vgs produces formatted output about VGs. diff --git a/man/vgs.8_end b/man/vgs.8_end new file mode 100644 index 0000000..b8cda26 --- /dev/null +++ b/man/vgs.8_end @@ -0,0 +1,17 @@ +.SH NOTES +. +The vg_attr bits are: +.IP 1 3 +Permissions: (w)riteable, (r)ead-only +.IP 2 3 +Resi(z)eable +.IP 3 3 +E(x)ported +.IP 4 3 +(p)artial: one or more physical volumes belonging to the volume group +are missing from the system +.IP 5 3 +Allocation policy: (c)ontiguous, c(l)ing, (n)ormal, (a)nywhere +.IP 6 3 +(c)lustered, (s)hared + diff --git a/man/vgs.8_pregen b/man/vgs.8_pregen new file mode 100644 index 0000000..c00460b --- /dev/null +++ b/man/vgs.8_pregen @@ -0,0 +1,642 @@ +.TH VGS 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgs \- Display information about volume groups +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgs\fP +.br + [ \fIoption_args\fP ] +.br + [ \fIposition_args\fP ] +.br +.P + +.SH DESCRIPTION +vgs produces formatted output about VGs. + +.P +.SH USAGE +.br +.P +. +\fBvgs\fP +.br +.RS 4 +.ad l +[ \fB-a\fP|\fB--all\fP ] +.ad b +.br +.ad l +[ \fB-o\fP|\fB--options\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB-S\fP|\fB--select\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB-O\fP|\fB--sort\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--aligned\fP ] +.ad b +.br +.ad l +[ \fB--binary\fP ] +.ad b +.br +.ad l +[ \fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP ] +.ad b +.br +.ad l +[ \fB--foreign\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--ignoreskippedcluster\fP ] +.ad b +.br +.ad l +[ \fB--logonly\fP ] +.ad b +.br +.ad l +[ \fB--nameprefixes\fP ] +.ad b +.br +.ad l +[ \fB--noheadings\fP ] +.ad b +.br +.ad l +[ \fB--nolocking\fP ] +.ad b +.br +.ad l +[ \fB--nosuffix\fP ] +.ad b +.br +.ad l +[ \fB--readonly\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +.ad l +[ \fB--rows\fP ] +.ad b +.br +.ad l +[ \fB--separator\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--shared\fP ] +.ad b +.br +.ad l +[ \fB--trustcache\fP ] +.ad b +.br +.ad l +[ \fB--unbuffered\fP ] +.ad b +.br +.ad l +[ \fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP ] +.ad b +.br +.ad l +[ \fB--unquoted\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br +.RS 4 +[ \fIVG\fP|\fITag\fP ... ] +.RE + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--aligned\fP +.br +Use with --separator to align the output columns +.ad b + +.HP +.ad l +\fB-a\fP|\fB--all\fP +.br +List all VGs. Equivalent to not specifying any VGs. +.ad b + +.HP +.ad l +\fB--binary\fP +.br +Use binary values "0" or "1" instead of descriptive literal values +for columns that have exactly two valid values to report (not counting +the "unknown" value which denotes that the value could not be determined). +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB--configreport\fP \fBlog\fP|\fBvg\fP|\fBlv\fP|\fBpv\fP|\fBpvseg\fP|\fBseg\fP +.br +See lvmreport(7). +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB--foreign\fP +.br +Report/display foreign VGs that would otherwise be skipped. +See lvmsystemid(7) for more information about foreign VGs. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--ignoreskippedcluster\fP +.br +Use to avoid exiting with an non-zero status code if the command is run +without clustered locking and clustered VGs are skipped. +.ad b + +.HP +.ad l +\fB--logonly\fP +.br +Suppress command report and display only log report. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--nameprefixes\fP +.br +Add an "LVM2_" prefix plus the field name to the output. Useful +with --noheadings to produce a list of field=value pairs that can +be used to set environment variables (for example, in udev rules). +.ad b + +.HP +.ad l +\fB--noheadings\fP +.br +Suppress the headings line that is normally the first line of output. +Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--nolocking\fP +.br +Disable locking. +.ad b + +.HP +.ad l +\fB--nosuffix\fP +.br +Suppress the suffix on output sizes. Use with --units +(except h and H) if processing the output. +.ad b + +.HP +.ad l +\fB-o\fP|\fB--options\fP \fIString\fP +.br +Comma-separated, ordered list of fields to display in columns. +String arg syntax is: [+|-|#]Field1[,Field2 ...] +The prefix \fB+\fP will append the specified fields to the default fields, +\fB-\fP will remove the specified fields from the default fields, and +\fB#\fP will compact specified fields (removing them when empty for all rows.) +Use \fB-o help\fP to view the list of all available fields. +The -o option can be repeated, providing several lists. +These lists are evaluated from left to right. +Use field name \fBlv_all\fP to view all LV fields, +\fBvg_all\fP all VG fields, +\fBpv_all\fP all PV fields, +\fBpvseg_all\fP all PV segment fields, +\fBseg_all\fP all LV segment fields, and +\fBpvseg_all\fP all PV segment columns. +See the lvm.conf report section for more config options. +See lvmreport(7) for more information about reporting. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--readonly\fP +.br +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. +It can also be used to peek inside the metadata of clustered VGs +when clustered locking is not configured or 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. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB--rows\fP +.br +Output columns as rows. +.ad b + +.HP +.ad l +\fB-S\fP|\fB--select\fP \fIString\fP +.br +Select objects for processing and reporting based on specified criteria. +The criteria syntax is described by \fB--select help\fP and \fBlvmreport\fP(7). +For reporting commands, one row is displayed for each object matching the criteria. +See \fB--options help\fP 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. +.ad b + +.HP +.ad l +\fB--separator\fP \fIString\fP +.br +String to use to separate each column. Useful if grepping the output. +.ad b + +.HP +.ad l +\fB--shared\fP +.br +Report/display shared VGs that would otherwise be skipped when +lvmlockd is not being used on the host. +See lvmlockd(8) for more information about shared VGs. +.ad b + +.HP +.ad l +\fB-O\fP|\fB--sort\fP \fIString\fP +.br +Comma-separated ordered list of columns to sort by. Replaces the default +selection. Precede any column with \fB-\fP for a reverse sort on that column. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB--trustcache\fP +.br +Avoids certain device scanning during command processing. Do not use. +.ad b + +.HP +.ad l +\fB--unbuffered\fP +.br +Produce output immediately without sorting or aligning the columns properly. +.ad b + +.HP +.ad l +\fB--units\fP \fBr\fP|\fBR\fP|\fBh\fP|\fBH\fP|\fBb\fP|\fBB\fP|\fBs\fP|\fBS\fP|\fBk\fP|\fBK\fP|\fBm\fP|\fBM\fP|\fBg\fP|\fBG\fP|\fBt\fP|\fBT\fP|\fBp\fP|\fBP\fP|\fBe\fP|\fBE\fP +.br +All sizes are output in these units: +human-(r)eadable with '<' rounding indicator, +(h)uman-readable, (b)ytes, (s)ectors, (k)ilobytes, (m)egabytes, +(g)igabytes, (t)erabytes, (p)etabytes, (e)xabytes. +Capitalise to use multiples of 1000 (S.I.) instead of 1024. +Custom units can be specified, e.g. --units 3M. +.ad b + +.HP +.ad l +\fB--unquoted\fP +.br +When used with --nameprefixes, output values in the field=value +pairs are not quoted. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fITag\fP +.br +Tag name. See \fBlvm\fP(8) for information about tag names and using tags +in place of a VG, LV or PV. + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH NOTES +. +The vg_attr bits are: +.IP 1 3 +Permissions: (w)riteable, (r)ead-only +.IP 2 3 +Resi(z)eable +.IP 3 3 +E(x)ported +.IP 4 3 +(p)artial: one or more physical volumes belonging to the volume group +are missing from the system +.IP 5 3 +Allocation policy: (c)ontiguous, c(l)ing, (n)ormal, @nywhere +.IP 6 3 +(c)lustered, (s)hared + +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgscan.8.des b/man/vgscan.8.des deleted file mode 100644 index e8041ed..0000000 --- a/man/vgscan.8.des +++ /dev/null @@ -1 +0,0 @@ -vgscan scans all supported LVM block devices in the system for VGs. diff --git a/man/vgscan.8_des b/man/vgscan.8_des new file mode 100644 index 0000000..e8041ed --- /dev/null +++ b/man/vgscan.8_des @@ -0,0 +1 @@ +vgscan scans all supported LVM block devices in the system for VGs. diff --git a/man/vgscan.8_end b/man/vgscan.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgscan.8_pregen b/man/vgscan.8_pregen new file mode 100644 index 0000000..57691ef --- /dev/null +++ b/man/vgscan.8_pregen @@ -0,0 +1,356 @@ +.TH VGSCAN 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgscan \- Search for all volume groups +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgscan\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgscan scans all supported LVM block devices in the system for VGs. + +.P +.SH USAGE +.br +.P +. +\fBvgscan\fP +.br +.RS 4 +.ad l +[ \fB-P\fP|\fB--partial\fP ] +.ad b +.br +.ad l +[ \fB--cache\fP ] +.ad b +.br +.ad l +[ \fB--ignorelockingfailure\fP ] +.ad b +.br +.ad l +[ \fB--mknodes\fP ] +.ad b +.br +.ad l +[ \fB--notifydbus\fP ] +.ad b +.br +.ad l +[ \fB--reportformat\fP \fBbasic\fP|\fBjson\fP ] +.ad b +.br +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--cache\fP +.br +Scan all devices and send the metadata to lvmetad. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--ignorelockingfailure\fP +.br +Allows a command to continue with read-only metadata +operations after locking failures. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB--mknodes\fP +.br +Also checks the LVM special files in /dev that are needed for active +LVs and creates any missing ones and removes unused ones. +.ad b + +.HP +.ad l +\fB--notifydbus\fP +.br +Send a notification to D-Bus. The command will exit with an error +if LVM is not built with support for D-Bus notification, or if the +notify_dbus config setting is disabled. +.ad b + +.HP +.ad l +\fB-P\fP|\fB--partial\fP +.br +When set, the tools will do their best to provide access to VGs +that are only partially available (one or more PVs belonging +to the VG are missing from the system). Metadata may not be +changed with this option. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB--reportformat\fP \fBbasic\fP|\fBjson\fP +.br +Overrides current output format for reports which is defined globally by +the report/output_format setting in lvm.conf. +\fBbasic\fP 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. \fBjson\fP produces report +output in JSON format. See \fBlvmreport\fP(7) for more information. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) + diff --git a/man/vgsplit.8.des b/man/vgsplit.8.des deleted file mode 100644 index 29eb5c5..0000000 --- a/man/vgsplit.8.des +++ /dev/null @@ -1,13 +0,0 @@ -vgsplit moves one or more PVs from a source VG to a destination VG. The -PVs can be specified explicitly or implicitly by naming an LV, in which -case on PVs underlying the LV are moved. - -If the destination VG does not exist, a new VG is created (command options -can be used to specify properties of the new VG, also see -\fBvgcreate\fP(8).) - -LVs cannot be split between VGs; each LV must be entirely on the PVs in -the source or destination VG. - -vgsplit can only move complete PVs. (See \fBpvmove\fP(8) for moving part -of a PV.) diff --git a/man/vgsplit.8_des b/man/vgsplit.8_des new file mode 100644 index 0000000..29eb5c5 --- /dev/null +++ b/man/vgsplit.8_des @@ -0,0 +1,13 @@ +vgsplit moves one or more PVs from a source VG to a destination VG. The +PVs can be specified explicitly or implicitly by naming an LV, in which +case on PVs underlying the LV are moved. + +If the destination VG does not exist, a new VG is created (command options +can be used to specify properties of the new VG, also see +\fBvgcreate\fP(8).) + +LVs cannot be split between VGs; each LV must be entirely on the PVs in +the source or destination VG. + +vgsplit can only move complete PVs. (See \fBpvmove\fP(8) for moving part +of a PV.) diff --git a/man/vgsplit.8_end b/man/vgsplit.8_end new file mode 100644 index 0000000..e69de29 diff --git a/man/vgsplit.8_pregen b/man/vgsplit.8_pregen new file mode 100644 index 0000000..a45db0b --- /dev/null +++ b/man/vgsplit.8_pregen @@ -0,0 +1,444 @@ +.TH VGSPLIT 8 "LVM TOOLS 2.02.169(2)-git (2016-11-30)" "Red Hat, Inc." +.SH NAME +. +vgsplit \- Move physical volumes into a new or existing volume group +.P +. +.SH SYNOPSIS +.br +.P +. +\fBvgsplit\fP \fIoption_args\fP \fIposition_args\fP +.br + [ \fIoption_args\fP ] +.br +.P + +.SH DESCRIPTION +vgsplit moves one or more PVs from a source VG to a destination VG. The +PVs can be specified explicitly or implicitly by naming an LV, in which +case on PVs underlying the LV are moved. + +If the destination VG does not exist, a new VG is created (command options +can be used to specify properties of the new VG, also see +\fBvgcreate\fP(8).) + +LVs cannot be split between VGs; each LV must be entirely on the PVs in +the source or destination VG. + +vgsplit can only move complete PVs. (See \fBpvmove\fP(8) for moving part +of a PV.) + +.P +.SH USAGE +.br +.P +. +Split a VG by specified PVs. +.br +.P +\fBvgsplit\fP \fIVG\fP \fIVG\fP \fIPV\fP ... +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Split a VG by PVs in a specified LV. +.br +.P +\fBvgsplit\fP \fB-n\fP|\fB--name\fP \fILV\fP \fIVG\fP \fIVG\fP +.br +.RS 4 +[ COMMON_OPTIONS ] +.RE +.br + + +Common options for command: +. +.RS 4 +.ad l +[ \fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-c\fP|\fB--clustered\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB-l\fP|\fB--maxlogicalvolumes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-p\fP|\fB--maxphysicalvolumes\fP \fINumber\fP ] +.ad b +.br +.ad l +[ \fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP ] +.ad b +.br +.ad l +[ \fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP ] +.ad b +.br +.ad l +[ \fB--[vg]metadatacopies\fP \fBall\fP|\fBunmanaged\fP|\fINumber\fP ] +.ad b + +.RE +.br + +Common options for lvm: +. +.RS 4 +.ad l +[ \fB-d\fP|\fB--debug\fP ] +.ad b +.br +.ad l +[ \fB-h\fP|\fB--help\fP ] +.ad b +.br +.ad l +[ \fB-q\fP|\fB--quiet\fP ] +.ad b +.br +.ad l +[ \fB-t\fP|\fB--test\fP ] +.ad b +.br +.ad l +[ \fB-v\fP|\fB--verbose\fP ] +.ad b +.br +.ad l +[ \fB-y\fP|\fB--yes\fP ] +.ad b +.br +.ad l +[ \fB--commandprofile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--config\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--driverloaded\fP \fBy\fP|\fBn\fP ] +.ad b +.br +.ad l +[ \fB--longhelp\fP ] +.ad b +.br +.ad l +[ \fB--profile\fP \fIString\fP ] +.ad b +.br +.ad l +[ \fB--version\fP ] +.ad b + +.RE + +.SH OPTIONS +.br + +.HP +.ad l +\fB--alloc\fP \fBcontiguous\fP|\fBcling\fP|\fBcling_by_tags\fP|\fBnormal\fP|\fBanywhere\fP|\fBinherit\fP +.br +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 overriden on the +command line. +\fBnormal\fP applies common sense rules such as not placing parallel stripes +on the same PV. +\fBinherit\fP applies the VG policy to an LV. +\fBcontiguous\fP requires new PEs be placed adjacent to existing PEs. +\fBcling\fP 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, \fBanywhere\fP 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 \fBlvm\fP(8) for more information about allocation. +.ad b + +.HP +.ad l +\fB-A\fP|\fB--autobackup\fP \fBy\fP|\fBn\fP +.br +Specifies if metadata should be backed up automatically after a change. +Enabling this is strongly advised! See vgcfgbackup(8) for more information. +.ad b + +.HP +.ad l +\fB-c\fP|\fB--clustered\fP \fBy\fP|\fBn\fP +.br +Specifies the clustered property of the new VG. +.ad b + +.HP +.ad l +\fB--commandprofile\fP \fIString\fP +.br +The command profile to use for command configuration. +See \fBlvm.conf\fP(5) for more information about profiles. +.ad b + +.HP +.ad l +\fB--config\fP \fIString\fP +.br +Config settings for the command. These override lvm.conf settings. +The String arg uses the same format as lvm.conf, +or may use section/field syntax. +See \fBlvm.conf\fP(5) for more information about config. +.ad b + +.HP +.ad l +\fB-d\fP|\fB--debug\fP ... +.br +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). +.ad b + +.HP +.ad l +\fB--driverloaded\fP \fBy\fP|\fBn\fP +.br +If set to no, the command will not attempt to use device-mapper. +For testing and debugging. +.ad b + +.HP +.ad l +\fB-h\fP|\fB--help\fP +.br +Display help text. +.ad b + +.HP +.ad l +\fB--longhelp\fP +.br +Display long help text. +.ad b + +.HP +.ad l +\fB-l\fP|\fB--maxlogicalvolumes\fP \fINumber\fP +.br +Sets the maximum number of LVs allowed in a VG. +.ad b + +.HP +.ad l +\fB-p\fP|\fB--maxphysicalvolumes\fP \fINumber\fP +.br +Sets the maximum number of PVs that can belong to the VG. +The value 0 removes any limitation. +For large numbers of PVs, also see options --pvmetadatacopies, +and --vgmetadatacopies for improving performance. +.ad b + +.HP +.ad l +\fB-M\fP|\fB--metadatatype\fP \fBlvm2\fP|\fBlvm1\fP +.br +Specifies the type of on-disk metadata to use. +\fBlvm2\fP (or just \fB2\fP) is the current, standard format. +\fBlvm1\fP (or just \fB1\fP) is a historical format that +can be used for accessing old data. +.ad b + +.HP +.ad l +\fB-n\fP|\fB--name\fP \fIString\fP +.br +Move only PVs used by the named LV. +.ad b + +.HP +.ad l +\fB--profile\fP \fIString\fP +.br +An alias for --commandprofile or --metadataprofile, depending +on the command. +.ad b + +.HP +.ad l +\fB-q\fP|\fB--quiet\fP ... +.br +Suppress output and log messages. Overrides --debug and --verbose. +Repeat once to also suppress any prompts with answer no. +.ad b + +.HP +.ad l +\fB-t\fP|\fB--test\fP +.br +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. +.ad b + +.HP +.ad l +\fB-v\fP|\fB--verbose\fP ... +.br +Set verbose level. Repeat from 1 to 4 times to increase the detail +of messages sent to stdout and stderr. +.ad b + +.HP +.ad l +\fB--version\fP +.br +Display version information. +.ad b + +.HP +.ad l +\fB--[vg]metadatacopies\fP \fBall\fP|\fBunmanaged\fP|\fINumber\fP +.br +Number of copies of the VG metadata that are kept. +VG metadata is kept in VG metadata areas on PVs in the VG, +i.e. reserved space@the start and/or end of the PVs. +Keeping a copy of the VG metadata on every PV can reduce performance +in VGs containing a large number of PVs. +When this number is set to a non-zero value, LVM will automatically +choose PVs on which to store metadata, using the metadataignore flags +on PVs to achieve the specified number. +The number can also be replaced with special string values: +\fBunmanaged\fP causes LVM to not automatically manage the PV +metadataignore flags. +\fBall\fP causes LVM to first clear the metadataignore flags on +all PVs, and then to become unmanaged. +.ad b + +.HP +.ad l +\fB-y\fP|\fB--yes\fP +.br +Do not prompt for confirmation interactively but always assume the +answer yes. Use with extreme caution. +(For automatic no, see -qq.) +.ad b +.SH VARIABLES +.br + +.HP +\fIVG\fP +.br +Volume Group name. See \fBlvm\fP(8) for valid names. + +.HP +\fIPV\fP +.br +Physical Volume name, a device path under /dev. +For commands managing physical extents, a PV positional arg +generally accepts a suffix indicating a range (or multiple ranges) +of physical extents (PEs). When the first PE is omitted, it defaults +to the start of the device, and when the last PE is omitted it defaults to end. +Start and end range (inclusive): \fIPV\fP[\fB:\fP\fIPE\fP\fB-\fP\fIPE\fP]... +Start and length range (counting from 0): \fIPV\fP[\fB:\fP\fIPE\fP\fB+\fP\fIPE\fP]... + +.HP +\fIString\fP +.br +See the option description for information about the string content. + +.HP +\fISize\fP[UNIT] +.br +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: \fBbBsSkKmMgGtTpPeE\fP. +b|B is bytes, s|S is sectors of 512 bytes, k|K is kilobytes, +m|M is megabytes, g|G is gigabytes, t|T is terabytes, +p|P is petabytes, e|E is exabytes. +(This should not be confused with the output control --units, where +capital letters mean multiple of 1000.) +.SH ENVIRONMENT VARIABLES +.br +See \fBlvm\fP(8) for information about environment variables used by lvm. +For example, LVM_VG_NAME can generally be substituted for a required VG parameter. +.SH SEE ALSO + +.BR lvm (8) +.BR lvm.conf (5) +.BR lvmconfig (8) + +.BR pvchange (8) +.BR pvck (8) +.BR pvcreate (8) +.BR pvdisplay (8) +.BR pvmove (8) +.BR pvremove (8) +.BR pvresize (8) +.BR pvs (8) +.BR pvscan (8) + +.BR vgcfgbackup (8) +.BR vgcfgrestore (8) +.BR vgchange (8) +.BR vgck (8) +.BR vgcreate (8) +.BR vgconvert (8) +.BR vgdisplay (8) +.BR vgexport (8) +.BR vgextend (8) +.BR vgimport (8) +.BR vgimportclone (8) +.BR vgmerge (8) +.BR vgmknodes (8) +.BR vgreduce (8) +.BR vgremove (8) +.BR vgrename (8) +.BR vgs (8) +.BR vgscan (8) +.BR vgsplit (8) + +.BR lvcreate (8) +.BR lvchange (8) +.BR lvconvert (8) +.BR lvdisplay (8) +.BR lvextend (8) +.BR lvreduce (8) +.BR lvremove (8) +.BR lvrename (8) +.BR lvresize (8) +.BR lvs (8) +.BR lvscan (8) + +.BR lvm2-activation-generator (8) +.BR blkdeactivate (8) +.BR lvmdump (8) + +.BR dmeventd (8) +.BR lvmetad (8) +.BR lvmpolld (8) +.BR lvmlockd (8) +.BR lvmlockctl (8) +.BR clvmd (8) +.BR cmirrord (8) +.BR lvmdbusd (8) + +.BR lvmsystemid (7) +.BR lvmreport (7) +.BR lvmraid (7) +.BR lvmthin (7) +.BR lvmcache (7) +