| .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) |
| |