NAME | DESCRIPTION | SEE ALSO | COLOPHON

LVMSYSTEMID(7)                                                LVMSYSTEMID(7)

NAME         top

       lvmsystemid — LVM system ID

DESCRIPTION         top

       Local VGs may exist on shared storage where they are visible to
       multiple 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 protects 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
       manually 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
       system_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 system_id.)

       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.

   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.

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

       · Two hosts should not be assigned the same system_id.  Doing so
         defeats the purpose of the system_id which is to distinguish
         different hosts.

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

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

SEE ALSO         top

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

COLOPHON         top

       This page is part of the lvm2 (Logical Volume Manager 2) project.
       Information about the project can be found at 
       ⟨http://www.sourceware.org/lvm2/⟩.  If you have a bug report for this
       manual page, send it to linux-lvm@redhat.com.  This page was obtained
       from the project's upstream Git repository 
       ⟨https://git.fedorahosted.org/git/lvm2.git⟩ on 2017-03-13.  If you
       discover any rendering problems in this HTML version of the page, or
       you believe there is a better or more up-to-date source for the page,
       or you have corrections or improvements to the information in this
       COLOPHON (which is not part of the original manual page), send a mail
       to man-pages@man7.org

Red Hat, Inc       LVM TOOLS 2.02.169(2)-git (2016-11-30)     LVMSYSTEMID(7)