diff options
Diffstat (limited to 'man/lvmsystemid.7.in')
-rw-r--r-- | man/lvmsystemid.7.in | 284 |
1 files changed, 284 insertions, 0 deletions
diff --git a/man/lvmsystemid.7.in b/man/lvmsystemid.7.in new file mode 100644 index 000000000..15b69a250 --- /dev/null +++ b/man/lvmsystemid.7.in @@ -0,0 +1,284 @@ +.TH "LVMSYSTEMID" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\"" + +.SH NAME +lvmsystemid \(em LVM system id + +.SH DESCRIPTION + +Local VG's may exist on shared storage where they are visible to multiple +hosts. These VG's 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 VG's 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 will ignore 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 +"foreign VG" is a VG with a system_id as viewed by a host with a system_id +that does not match the VG's system_id. (Or from a host without a +system_id.) + +To benefit fully from system_id, all hosts must have system_id set, and +VGs must have system_id set. Two hosts should not be assigned the same +system_id. Doing so defeats the purpose of the 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 Types of VG access +A "local VG" is meant to be used by a single host. +.br +A "shared 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 Clustered: +A shared VG with the clustered flag set, and no system_id. This VG type +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 +allow_system_id 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 allow_system_id + +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/allow_system_id. + +.I lvmlocal.conf +.nf +local { + allow_system_id = [ "my_other_name" ] +} +.fi + +.SS vgcreate + +In vgcreate, a host sets its own system_id in the VG metadata. +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. + +.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 all VGs to be read +from disk. + +.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_sources. 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 + +If a VG has a system_id, changing it with vgchange requires --force. +vgchange --systemid is accepted just as with vgcreate. + +If a host's system_id is changed, the system_id of its own VG's can be +changed to match. Using allow_system_id is a way to avoid using force +with vgchange. + +To move a VG from one host to another, vgexport and vgimport should be +used. + +.SS clustered VGs + +A "clustered" VG should have no system_id set, allowing multiple hosts to +use it via clvm. 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. Coodination 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. If the other hosts run a command to rescan +devices, and update lvmetad, they would then recognize the PV has become +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) + |