1LVMSYSTEMID(7)                                                  LVMSYSTEMID(7)
2
3
4

NAME

6       lvmsystemid — LVM system ID
7
8

DESCRIPTION

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

SEE ALSO

339       vgcreate(8),   vgchange(8),   vgimport(8),  vgexport(8),  vgs(8),  lvm‐
340       lockd(8), lvm.conf(5), machine-id(5), uname(2)
341
342
343
344
345Red Hat, Inc           LVM TOOLS 2.03.11(2) (2021-01-08)        LVMSYSTEMID(7)
Impressum