LVMSYSTEMID(7)							LVMSYSTEMID(7)



NAME
       lvmsystemid -- LVM system ID


DESCRIPTION
       Local  VGs may exist on shared storage where they are visible to multi-
       ple 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 pro-
       tects 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 manu-
       ally  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  sys-
       tem_id can only be used by a host with a matching system_id.  A 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 sys-
       tem_id.)

       Valid system_id characters are the same as valid	 VG  name  characters.
       If  a system_id contains invalid characters, those characters are omit-
       ted 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.


   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.


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


       o Two hosts should not  be  assigned  the  same	system_id.   Doing  so
	 defeats  the purpose of the system_id which is to distinguish differ-
	 ent hosts.


       o 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  con-
	 flicting  operations and corrupting the PVs.  See the orphans section
	 for more information.


       o 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  sys-
	 tem_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 downgrad-
	 ing to an lvm version without the system_id feature.


   Types of VG access
       A local VG is meant to be used by a single host.
       A shared or clustered VG is meant to be used by multiple hosts.
       These can be further distinguished as:

       Unrestricted: A local VG that has no system_id.	This VG type is unpro-
       tected and accessible to any host.

       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.

       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.

       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.

       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.

       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.


   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:


       none

	      lvm will not use a system_id.  lvm  is  allowed  to  access  VGs
	      without  a  system_id,  and  will	 create new VGs without a sys-
	      tem_id.  An undefined system_id_source is equivalent to none.

	      lvm.conf
	      global {
		  system_id_source = "none"
	      }


       machineid

	      The content of /etc/machine-id  is  used	as  the	 system_id  if
	      available.  See machine-id(5) and systemd-machine-id-setup(1) to
	      check if machine-id is available on the host.

	      lvm.conf
	      global {
		  system_id_source = "machineid"
	      }


       uname

	      The string utsname.nodename from uname(2) is used	 as  the  sys-
	      tem_id.	A  uname  beginning  with  "localhost"	is ignored and
	      equivalent to none.

	      lvm.conf
	      global {
		  system_id_source = "uname"
	      }


       lvmlocal

	      The system_id is defined in lvmlocal.conf local/system_id.

	      lvm.conf
	      global {
		  system_id_source = "lvmlocal"
	      }

	      lvmlocal.conf
	      local {
		  system_id = "example_name"
	      }


       file

	      The system_id  is	 defined  in  a	 file  specified  by  lvm.conf
	      global/system_id_file.

	      lvm.conf
	      global {
		  system_id_source = "file"
		  system_id_file = "/path/to/file"
	      }


       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.


   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.

       lvmlocal.conf
       local {
	   extra_system_ids = [ "my_other_name" ]
       }


   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:

       vgcreate --systemid 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 rescan-
       ning 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.)


   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  for-
       eign  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.

       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.


   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.


   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:

       vgchange --systemid 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.


   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.


   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.


   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.


   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 com-
       mand that rescans devices could be pvscan --cache, or vgs --foreign.


SEE ALSO
       vgcreate(8),  vgchange(8),   vgimport(8),   vgexport(8),	  lvm.conf(5),
       machine-id(5), uname(2), vgs(8)




Red Hat, Inc	   LVM TOOLS 2.02.166(2)-RHEL7 (2016-11-16)	LVMSYSTEMID(7)