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

NAME

6       lvmsystemid — LVM system ID
7

DESCRIPTION

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
16       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
21       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
26       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
32       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
37       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
44       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
52       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
58       Print the system ID of a VG to check if it is set:
59
60       vgs -o systemid VG
61
62       Print the system ID of the local host to check if it is configured:
63
64       lvm systemid
65
66   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
72       • 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
75       • 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
80       • 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
83       • 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
89       • The system ID does not protect devices in a VG  from  programs  other
90         than LVM.
91
92       • 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
98         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
103   Types of VG access
104       A local VG is meant to be used by a single host.
105
106       A shared or clustered VG is meant to be used by multiple hosts.
107
108       These can be further distinguished as:
109
110       Unrestricted:
111              A local VG that has no system ID.  This VG type  is  unprotected
112              and accessible to any host.
113
114       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
118       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
123       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
128       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
134       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
140   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
145       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
150              lvm.conf
151              global {
152                  system_id_source = "none"
153              }
154
155       appmachineid
156
157              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
161              lvm.conf
162              global {
163                  system_id_source = "appmachineid"
164              }
165
166
167       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
173              lvm.conf
174              global {
175                  system_id_source = "machineid"
176              }
177
178       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
183              lvm.conf
184              global {
185                  system_id_source = "uname"
186              }
187
188       lvmlocal
189              The system ID is defined in lvmlocal.conf local/system_id.
190
191              lvm.conf
192              global {
193                  system_id_source = "lvmlocal"
194              }
195
196              lvmlocal.conf
197              local {
198                  system_id = "example_name"
199              }
200
201       file
202              The system ID  is  defined  in  a  file  specified  by  lvm.conf
203              global/system_id_file.
204
205              lvm.conf
206              global {
207                  system_id_source = "file"
208                  system_id_file = "/path/to/file"
209              }
210
211       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
215       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
220   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
227       lvmlocal.conf
228       local {
229           extra_system_ids = [ "my_other_name" ]
230       }
231
232       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
236   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
240       vgcreate --systemid SystemID VG PVs
241
242       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
247       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
251   report/display
252       The  system  ID  of a VG is displayed with the "systemid" reporting op‐
253       tion.
254
255       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
259       vgs --foreign -o +systemid
260
261       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
265   vgexport/vgimport
266       vgexport clears the VG system ID when exporting the VG.
267
268       vgimport sets the VG system ID to the system ID of the host  doing  the
269       import.
270
271   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
276       vgchange --systemid SystemID VG
277
278       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
282       A host cannot directly change the system ID of a foreign VG.
283
284       To  move a VG from one host to another, vgexport and vgimport should be
285       used.
286
287       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
291   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
296   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
302   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
308   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

SEE ALSO

316       vgcreate(8), vgchange(8), vgimport(8), vgexport(8), vgs(8),
317       lvmlockd(8), lvm.conf(5), machine-id(5), uname(2)
318
319
320
321Red Hat, Inc         LVM TOOLS 2.03.18(2)-git (2022-11-10)      LVMSYSTEMID(7)
Impressum