NAME

       lvmsystemid — LVM system ID

DESCRIPTION

       The  lvm(8) system ID restricts Volume Group (VG) access to one host.  This is useful when
       a VG is placed on shared storage devices, or when local devices are visible to  both  host
       and  guest  operating systems.  In cases like these, a VG can be visible to multiple hosts
       at once, and some mechanism is needed to protect it from being used by more than one  host
       at a time.

       A  VG's system ID identifies one host as the VG owner.  The host with a matching system ID
       can use the VG and its LVs, while LVM on other hosts will ignore it.  This protects the VG
       from being accidentally used from other hosts.

       The  system  ID  is  a  string that uniquely identifies a host.  It can be configured as a
       custom value, or it can be assigned automatically by  LVM  using  some  unique  identifier
       already available on the host, e.g.  machine-id or uname.

       When  a new VG is created, the system ID of the local host is recorded in the VG metadata.
       The creating host then owns the new VG, and LVM on other hosts will ignore  it.   When  an
       existing,  exported VG is imported (vgimport), the system ID of the local host is saved in
       the VG metadata, and the importing host owns the VG.

       A VG without a system ID can be used by LVM  on  any  host  where  the  VG's  devices  are
       visible.   When  system IDs are not used, device filters should be configured on all hosts
       to exclude the VG's devices from all but one host.

       A foreign VG is a VG seen by a host with an unmatching system ID, i.e. the  system  ID  in
       the  VG  metadata does not match the system ID configured on the host.  If the host has no
       system ID, and the VG does, the VG is foreign and LVM will ignore it.  If the  VG  has  no
       system  ID,  access is unrestricted, and LVM can access it from any host, whether the host
       has a system ID or not.

       Changes to a host's system ID and a VG's system ID can be made  in  limited  circumstances
       (see  vgexport  and vgimport).  Improper changes can result in a host losing access to its
       VG, or a VG being accidentally damaged by access from an unintended  host.   Even  limited
       changes  to the VG system ID may not be perfectly reflected across hosts.  A more coherent
       view of shared storage requires an inter-host locking  system  to  coordinate  access  and
       update caches.

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

       Print the system ID of a VG to check if it is set:

       vgs -o systemid VG

       Print the system ID of the local host to check if it is configured:

       lvm systemid

   Limitations and warnings
       To benefit fully from system ID, all hosts should have a system ID configured, and all VGs
       should  have  a  system  ID set.  Without any method to restrict access, e.g. system ID or
       device filters, a VG that is visible to multiple hosts  can  be  accidentally  damaged  or
       destroyed.

       • A  VG  without  a  system  ID  can be used without restriction from any host where it is
         visible, even from hosts that have a system ID.

       • Many VGs will not have a system ID set because LVM has not enabled it  by  default,  and
         even when enabled, many VGs were created before the feature was added to LVM or enabled.
         A system ID can be assigned to these VGs by using vgchange --systemid (see below).

       • Two hosts should not be assigned the same system ID.  Doing so defeats  the  purpose  of
         distinguishing different hosts with this value.

       • Orphan  PVs  (or  unused  devices)  on  shared  storage are unprotected by the system ID
         feature.  Commands that use these PVs, such as vgcreate or vgextend, are  not  prevented
         from  performing conflicting operations and corrupting the PVs.  See the orphans section
         for more information.

       • The system ID does not protect devices in a VG from programs other than LVM.

       • A host using an old LVM version (without the system ID feature)  will  not  recognize  a
         system ID set in VGs.  The old LVM can read a VG with a system ID, but is prevented from
         writing to the VG (or its LVs).  The system ID feature changes the write mode of  a  VG,
         making it appear read-only to previous versions of LVM.

         This  also  means that if a host downgrades to the old LVM version, it would lose access
         to any VGs it had created with a system ID.  To avoid this,  the  system  ID  should  be
         removed  from  local  VGs  before  downgrading  LVM  to  a 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  unprotected  and
       accessible to any host.

       Owned: A local VG that has a system ID set, as viewed from the host with a matching system
       ID (the owner).  This VG type is acessible to the host.

       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 not accessible
       to the host.

       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 the lock_type set and has 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 lvmlockd support.

       Clustered:  A  clustered  or "clvm" VG has the clustered flag set and has 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. Applicable only if LVM is compiled with clvm support.

   Host system ID configuration
       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 system 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  system  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  likely  cause the system ID of the host to change, which
       will 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 produce a system ID value, it is the
       equivalent of having none.  The host will be allowed to access VGs with no system ID,  but
       will not be allowed to access VGs with a system ID set.

   Overriding system ID
       In  some  cases,  it  may be necessary for a host to access VGs with different system IDs,
       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 IDs, those other system IDs
       can be listed in lvmlocal.conf local/extra_system_ids.

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

       A safer option may be configuring the extra values as needed on the command line as:
       --config 'local/extra_system_ids=["id"]'

   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 PVs

       Overriding  the  host's  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 rescanning 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  foreign  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 system ID of the host doing  the  import.   vgimport
       automatically scans storage for newly exported VGs.

       After  vgimport,  the exporting host may 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 temporarily add the foreign system
       ID to its extra_system_ids list, and change the system ID of the foreign VG  to  its  own.
       See Overriding system ID above.

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

SEE ALSO

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