1LVMSYSTEMID(7) LVMSYSTEMID(7)
2
6 lvmsystemid — LVM system ID
7
9 The lvm(8) system ID restricts Volume Group (VG) access to one host.
10 This is useful when a VG is placed on shared storage devices, or when
11 local devices are visible to both host and guest operating systems. In
12 cases like these, a VG can be visible to multiple hosts at once, and
13 some mechanism is needed to protect it from being used by more than one
14 host at a time.
15 A VG's system ID identifies one host as the VG owner. The host with a
17 matching system ID can use the VG and its LVs, while LVM on other hosts
18 will ignore it. This protects the VG from being accidentally used from
19 other hosts.
20 The system ID is a string that uniquely identifies a host. It can be
22 configured as a custom value, or it can be assigned automatically by
23 LVM using some unique identifier already available on the host, e.g.
24 machine-id or uname.
25 When a new VG is created, the system ID of the local host is recorded
27 in the VG metadata. The creating host then owns the new VG, and LVM on
28 other hosts will ignore it. When an existing, exported VG is imported
29 (vgimport), the system ID of the local host is saved in the VG meta‐
30 data, and the importing host owns the VG.
31 A VG without a system ID can be used by LVM on any host where the VG's
33 devices are visible. When system IDs are not used, device filters
34 should be configured on all hosts to exclude the VG's devices from all
35 but one host.
36 A foreign VG is a VG seen by a host with an unmatching system ID, i.e.
38 the system ID in the VG metadata does not match the system ID config‐
39 ured on the host. If the host has no system ID, and the VG does, the
40 VG is foreign and LVM will ignore it. If the VG has no system ID, ac‐
41 cess is unrestricted, and LVM can access it from any host, whether the
42 host has a system ID or not.
43 Changes to a host's system ID and a VG's system ID can be made in lim‐
45 ited circumstances (see vgexport and vgimport). Improper changes can
46 result in a host losing access to its VG, or a VG being accidentally
47 damaged by access from an unintended host. Even limited changes to the
48 VG system ID may not be perfectly reflected across hosts. A more co‐
49 herent view of shared storage requires an inter-host locking system to
50 coordinate access.
51 Valid system ID characters are the same as valid VG name characters.
53 If a system ID contains invalid characters, those characters are omit‐
54 ted and remaining characters are used. If a system ID is longer than
55 the maximum name length, the characters up to the maximum length are
56 used. The maximum length of a system ID is 128 characters.
57 Print the system ID of a VG to check if it is set:
59 vgs -o systemid VG
61 Print the system ID of the local host to check if it is configured:
63 lvm systemid
65 Limitations and warnings
67 To benefit fully from system ID, all hosts should have a system ID con‐
68 figured, and all VGs should have a system ID set. Without any method
69 to restrict access, e.g. system ID or device filters, a VG that is vis‐
70 ible to multiple hosts can be accidentally damaged or destroyed.
71 • A VG without a system ID can be used without restriction from any
73 host where it is visible, even from hosts that have a system ID.
74 • Many VGs will not have a system ID set because LVM has not enabled it
76 by default, and even when enabled, many VGs were created before the
77 feature was added to LVM or enabled. A system ID can be assigned to
78 these VGs by using vgchange --systemid (see below).
79 • Two hosts should not be assigned the same system ID. Doing so de‐
81 feats the purpose of distinguishing different hosts with this value.
82 • Orphan PVs (or unused devices) on shared storage are unprotected by
84 the system ID feature. Commands that use these PVs, such as vgcreate
85 or vgextend, are not prevented from performing conflicting operations
86 and corrupting the PVs. See the orphans section for more informa‐
87 tion.
88 • The system ID does not protect devices in a VG from programs other
90 than LVM.
91 • A host using an old LVM version (without the system ID feature) will
93 not recognize a system ID set in VGs. The old LVM can read a VG with
94 a system ID, but is prevented from writing to the VG (or its LVs).
95 The system ID feature changes the write mode of a VG, making it ap‐
96 pear read-only to previous versions of LVM.
97 This also means that if a host downgrades to the old LVM version, it
99 would lose access to any VGs it had created with a system ID. To
100 avoid this, the system ID should be removed from local VGs before
101 downgrading LVM to a version without the system ID feature.
102 Types of VG access
104 A local VG is meant to be used by a single host.
105 A shared or clustered VG is meant to be used by multiple hosts.
107 These can be further distinguished as:
109 Unrestricted:
111 A local VG that has no system ID. This VG type is unprotected
112 and accessible to any host.
113 Owned: A local VG that has a system ID set, as viewed from the host
115 with a matching system ID (the owner). This VG type is accessi‐
116 ble to the host.
117 Foreign:
119 A local VG that has a system ID set, as viewed from any host
120 with an unmatching system ID (or no system ID). It is owned by
121 another host. This VG type is not accessible to the host.
122 Exported:
124 A local VG that has been exported with vgexport and has no sys‐
125 tem ID. This VG type can only be accessed by vgimport which
126 will change it to owned.
127 Shared:
129 A shared or "lockd" VG has the lock_type set and has no system
130 ID. A shared VG is meant to be used on shared storage from mul‐
131 tiple hosts, and is only accessible to hosts using lvmlockd. Ap‐
132 plicable only if LVM is compiled with lvmlockd support.
133 Clustered:
135 A clustered or "clvm" VG has the clustered flag set and has no
136 system ID. A clustered VG is meant to be used on shared storage
137 from multiple hosts, and is only accessible to hosts using
138 clvmd. Applicable only if LVM is compiled with clvm support.
139 Host system ID configuration
141 A host's own system ID can be defined in a number of ways. lvm.conf
142 global/system_id_source defines the method LVM will use to find the lo‐
143 cal system ID:
144 none
146 LVM will not use a system ID. LVM is allowed to access VGs
147 without a system ID, and will create new VGs without a system
148 ID. An undefined system_id_source is equivalent to none.
149 lvm.conf
151 global {
152 system_id_source = "none"
153 }
154 appmachineid
156 An LVM-specific derivation of /etc/machine-id is used as the
158 system ID. See machine-id(5) to check if machine-id is avail‐
159 able on the host.
160 lvm.conf
162 global {
163 system_id_source = "appmachineid"
164 }
165 machineid
168 The content of /etc/machine-id is used as the system ID if
169 available. See machine-id(5) and systemd-machine-id-setup(1) to
170 check if machine-id is available on the host. (appmachineid is
171 recommended in place of machineid.)
172 lvm.conf
174 global {
175 system_id_source = "machineid"
176 }
177 uname
179 The string utsname.nodename from uname(2) is used as the system
180 ID. A uname beginning with "localhost" is ignored and equiva‐
181 lent to none.
182 lvm.conf
184 global {
185 system_id_source = "uname"
186 }
187 lvmlocal
189 The system ID is defined in lvmlocal.conf local/system_id.
190 lvm.conf
192 global {
193 system_id_source = "lvmlocal"
194 }
195 lvmlocal.conf
197 local {
198 system_id = "example_name"
199 }
200 file
202 The system ID is defined in a file specified by lvm.conf
203 global/system_id_file.
204 lvm.conf
206 global {
207 system_id_source = "file"
208 system_id_file = "/path/to/file"
209 }
210 Changing system_id_source will likely cause the system ID of the host
212 to change, which will prevent the host from using VGs that it previ‐
213 ously used (see extra_system_ids below to handle this.)
214 If a system_id_source other than none fails to produce a system ID
216 value, it is the equivalent of having none. The host will be allowed
217 to access VGs with no system ID, but will not be allowed to access VGs
218 with a system ID set.
219 Overriding system ID
221 In some cases, it may be necessary for a host to access VGs with dif‐
222 ferent system IDs, e.g. if a host's system ID changes, and it wants to
223 use VGs that it created with its old system ID. To allow a host to ac‐
224 cess VGs with other system IDs, those other system IDs can be listed in
225 lvmlocal.conf local/extra_system_ids.
226 lvmlocal.conf
228 local {
229 extra_system_ids = [ "my_other_name" ]
230 }
231 A safer option may be configuring the extra values as needed on the
233 command line as:
234 --config 'local/extra_system_ids=["id"]'
235 vgcreate
237 In vgcreate, the host running the command assigns its own system ID to
238 the new VG. To override this and set another system ID:
239 vgcreate --systemid SystemID VG PVs
241 Overriding the host's system ID makes it possible for a host to create
243 a VG that it may not be able to use. Another host with a system ID
244 matching the one specified may not recognize the new VG without manu‐
245 ally rescanning devices.
246 If the --systemid argument is an empty string (""), the VG is created
248 with no system ID, making it accessible to other hosts (see warnings
249 above.)
250 report/display
252 The system ID of a VG is displayed with the "systemid" reporting op‐
253 tion.
254 Report/display commands ignore foreign VGs by default. To report for‐
256 eign VGs, the --foreign option can be used. This causes the VGs to be
257 read from disk.
258 vgs --foreign -o +systemid
260 When a host with no system ID sees foreign VGs, it warns about them as
262 they are skipped. The host should be assigned a system ID, after which
263 standard reporting commands will silently ignore foreign VGs.
264 vgexport/vgimport
266 vgexport clears the VG system ID when exporting the VG.
267 vgimport sets the VG system ID to the system ID of the host doing the
269 import.
270 vgchange
272 A host can change the system ID of its own VGs, but the command re‐
273 quires confirmation because the host may lose access to the VG being
274 changed:
275 vgchange --systemid SystemID VG
277 The system ID can be removed from a VG by specifying an empty string
279 ("") as the new system ID. This makes the VG accessible to other hosts
280 (see warnings above.)
281 A host cannot directly change the system ID of a foreign VG.
283 To move a VG from one host to another, vgexport and vgimport should be
285 used.
286 To forcibly gain ownership of a foreign VG, a host can temporarily add
288 the foreign system ID to its extra_system_ids list, and change the sys‐
289 tem ID of the foreign VG to its own. See Overriding system ID above.
290 shared VGs
292 A shared VG has no system ID set, allowing multiple hosts to use it via
293 lvmlockd. Changing a VG to shared will clear the existing system ID.
294 Applicable only if LVM is compiled with lvmlockd support.
295 clustered VGs
297 A clustered/clvm VG has no system ID set, allowing multiple hosts to
298 use it via clvmd. Changing a VG to clustered will clear the existing
299 system ID. Changing a VG to not clustered will set the system ID to
300 the host running the vgchange command.
301 creation_host
303 In vgcreate, the VG metadata field creation_host is set by default to
304 the host's uname. The creation_host cannot be changed, and is not used
305 to control access. When system_id_source is "uname", the system_id and
306 creation_host fields will be the same.
307 orphans
309 Orphan PVs are unused devices; they are not currently used in any VG.
310 Because of this, they are not protected by a system ID, and any host
311 can use them. Coordination of changes to orphan PVs is beyond the
312 scope of system ID. The same is true of any block device that is not a
313 PV.
314
316 vgcreate(8), vgchange(8), vgimport(8), vgexport(8), vgs(8),
317 lvmlockd(8), lvm.conf(5), machine-id(5), uname(2)
318Red Hat, Inc LVM TOOLS 2.03.18(2)-git (2022-11-10) LVMSYSTEMID(7)