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,
42       access  is  unrestricted,  and LVM can access it from any host, whether
43       the 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
50       coherent  view  of shared storage requires an inter-host locking system
51       to 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
86         defeats the purpose  of  distinguishing  different  hosts  with  this
87         value.
88
89
90       · Orphan  PVs  (or unused devices) on shared storage are unprotected by
91         the system ID feature.  Commands that use these PVs, such as vgcreate
92         or vgextend, are not prevented from performing conflicting operations
93         and corrupting the PVs.  See the orphans section  for  more  informa‐
94         tion.
95
96
97       · The  system  ID  does not protect devices in a VG from programs other
98         than LVM.
99
100
101       · A host using an old LVM version (without the system ID feature)  will
102         not recognize a system ID set in VGs.  The old LVM can read a VG with
103         a system ID, but is prevented from writing to the VG  (or  its  LVs).
104         The  system  ID  feature  changes  the  write mode of a VG, making it
105         appear read-only to previous versions of LVM.
106
107         This also means that if a host downgrades to the old LVM version,  it
108         would  lose  access  to  any VGs it had created with a system ID.  To
109         avoid this, the system ID should be removed  from  local  VGs  before
110         downgrading LVM to a version without the system ID feature.
111
112
113
114   Types of VG access
115       A local VG is meant to be used by a single host.
116
117       A shared or clustered VG is meant to be used by multiple hosts.
118
119       These can be further distinguished as:
120
121       Unrestricted: A local VG that has no system ID.  This VG type is unpro‐
122       tected and accessible to any host.
123
124       Owned: A local VG that has a system ID set, as  viewed  from  the  host
125       with  a  matching  system ID (the owner).  This VG type is acessible to
126       the host.
127
128       Foreign: A local VG that has a system ID set, as viewed from  any  host
129       with an unmatching system ID (or no system ID).  It is owned by another
130       host.  This VG type is not accessible to the host.
131
132       Exported: A local VG that has been exported with vgexport  and  has  no
133       system  ID.   This  VG type can only be accessed by vgimport which will
134       change it to owned.
135
136       Shared: A shared or "lockd" VG has the lock_type set and has no  system
137       ID.   A  shared  VG is meant to be used on shared storage from multiple
138       hosts, and is only accessible to hosts using lvmlockd. Applicable  only
139       if LVM is compiled with lvmlockd support.
140
141       Clustered:  A clustered or "clvm" VG has the clustered flag set and has
142       no system ID.  A clustered VG is meant to be  used  on  shared  storage
143       from  multiple  hosts,  and  is  only  accessible to hosts using clvmd.
144       Applicable only if LVM is compiled with clvm support.
145
146
147
148   Host system ID configuration
149       A host's own system ID can be defined in a number  of  ways.   lvm.conf
150       global/system_id_source  defines  the  method  LVM will use to find the
151       local system ID:
152
153
154       none
155
156              LVM will not use a system ID.  LVM  is  allowed  to  access  VGs
157              without  a  system  ID, and will create new VGs without a system
158              ID.  An undefined system_id_source is equivalent to none.
159
160              lvm.conf
161              global {
162                  system_id_source = "none"
163              }
164
165
166       machineid
167
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.
171
172              lvm.conf
173              global {
174                  system_id_source = "machineid"
175              }
176
177
178       uname
179
180              The string utsname.nodename from uname(2) is used as the  system
181              ID.   A  uname beginning with "localhost" is ignored and equiva‐
182              lent to none.
183
184              lvm.conf
185              global {
186                  system_id_source = "uname"
187              }
188
189
190       lvmlocal
191
192              The system ID is defined in lvmlocal.conf local/system_id.
193
194              lvm.conf
195              global {
196                  system_id_source = "lvmlocal"
197              }
198
199              lvmlocal.conf
200              local {
201                  system_id = "example_name"
202              }
203
204
205       file
206
207              The system ID  is  defined  in  a  file  specified  by  lvm.conf
208              global/system_id_file.
209
210              lvm.conf
211              global {
212                  system_id_source = "file"
213                  system_id_file = "/path/to/file"
214              }
215
216
217       Changing  system_id_source  will likely cause the system ID of the host
218       to change, which will prevent the host from using VGs  that  it  previ‐
219       ously used (see extra_system_ids below to handle this.)
220
221       If  a  system_id_source  other  than  none fails to produce a system ID
222       value, it is the equivalent of having none.  The host will  be  allowed
223       to  access VGs with no system ID, but will not be allowed to access VGs
224       with a system ID set.
225
226
227
228   Overriding system ID
229       In some cases, it may be necessary for a host to access VGs  with  dif‐
230       ferent  system IDs, e.g. if a host's system ID changes, and it wants to
231       use VGs that it created with its old system ID.  To  allow  a  host  to
232       access  VGs with other system IDs, those other system IDs can be listed
233       in lvmlocal.conf local/extra_system_ids.
234
235       lvmlocal.conf
236       local {
237           extra_system_ids = [ "my_other_name" ]
238       }
239
240       A safer option may be configuring the extra values  as  needed  on  the
241       command line as:
242       --config 'local/extra_system_ids=["id"]'
243
244
245
246   vgcreate
247       In  vgcreate, the host running the command assigns its own system ID to
248       the new VG.  To override this and set another system ID:
249
250       vgcreate --systemid SystemID VG PVs
251
252       Overriding the host's system ID makes it possible for a host to  create
253       a  VG  that  it  may not be able to use.  Another host with a system ID
254       matching the one specified may not recognize the new VG  without  manu‐
255       ally rescanning devices.
256
257       If  the  --systemid argument is an empty string (""), the VG is created
258       with no system ID, making it accessible to other  hosts  (see  warnings
259       above.)
260
261
262
263   report/display
264       The  system  ID  of  a  VG  is  displayed with the "systemid" reporting
265       option.
266
267       Report/display commands ignore foreign VGs by default.  To report  for‐
268       eign  VGs, the --foreign option can be used.  This causes the VGs to be
269       read from disk.
270
271       vgs --foreign -o +systemid
272
273       When a host with no system ID sees foreign VGs, it warns about them  as
274       they are skipped.  The host should be assigned a system ID, after which
275       standard reporting commands will silently ignore foreign VGs.
276
277
278
279   vgexport/vgimport
280       vgexport clears the VG system ID when exporting the VG.
281
282       vgimport sets the VG system ID to the system ID of the host  doing  the
283       import.
284
285
286
287   vgchange
288       A  host  can  change  the  system  ID  of  its own VGs, but the command
289       requires confirmation because the host may lose access to the VG  being
290       changed:
291
292       vgchange --systemid SystemID VG
293
294       The  system  ID  can be removed from a VG by specifying an empty string
295       ("") as the new system ID.  This makes the VG accessible to other hosts
296       (see warnings above.)
297
298       A host cannot directly change the system ID of a foreign VG.
299
300       To  move a VG from one host to another, vgexport and vgimport should be
301       used.
302
303       To forcibly gain ownership of a foreign VG, a host can temporarily  add
304       the foreign system ID to its extra_system_ids list, and change the sys‐
305       tem ID of the foreign VG to its own.  See Overriding system ID above.
306
307
308
309   shared VGs
310       A shared VG has no system ID set, allowing multiple hosts to use it via
311       lvmlockd.   Changing  a VG to shared will clear the existing system ID.
312       Applicable only if LVM is compiled with lvmlockd support.
313
314
315
316   clustered VGs
317       A clustered/clvm VG has no system ID set, allowing  multiple  hosts  to
318       use  it  via clvmd.  Changing a VG to clustered will clear the existing
319       system ID.  Changing a VG to not clustered will set the  system  ID  to
320       the host running the vgchange command.
321
322
323
324   creation_host
325       In  vgcreate,  the VG metadata field creation_host is set by default to
326       the host's uname.  The creation_host cannot be changed, and is not used
327       to control access.  When system_id_source is "uname", the system_id and
328       creation_host fields will be the same.
329
330
331   orphans
332       Orphan PVs are unused devices; they are not currently used in  any  VG.
333       Because  of  this,  they are not protected by a system ID, and any host
334       can use them.  Coordination of changes to  orphan  PVs  is  beyond  the
335       scope of system ID.  The same is true of any block device that is not a
336       PV.
337
338

SEE ALSO

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