Provided by: lvm2_2.02.133-1ubuntu10_amd64 bug

NAME

       lvmsystemid — LVM system ID

DESCRIPTION

       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.

       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.

   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

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