# lvmsystemid

## 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.
    
           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 accessible 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"
                  }
    
           **appmachineid**
                  An LVM-specific derivation of /etc/machine-id is used as
                  the system ID.  See machine-id(5) to check if machine-id is
                  available on the host.
    
                  _lvm.conf_
                  global {
                      system_id_source = "appmachineid"
                  }
    
           **machineid**
                  The content of /etc/machine-id is used as the system ID if
                  available.  (appmachineid is recommended to avoid exposing
                  the confidential machine-id.)
    
                  _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.
    
           **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 VG system ID when exporting the VG.
    
           vgimport sets the VG system ID to the system ID of the host doing
           the import.
    
       **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 VG has no system ID set, allowing multiple hosts to use
           it via lvmlockd.  Changing a VG to shared will clear the existing
           system ID.  Applicable only if LVM is compiled with lvmlockd
           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.
    


* * *