path: root/man/lvmsystemid.7.in

.TH "LVMSYSTEMID" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\""

.SH NAME
lvmsystemid \(em LVM system id

.SH DESCRIPTION

Local VG's may exist on shared storage where they are visible to multiple
hosts.  These VG's 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 VG's 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 will ignore 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 VG's system_id.  (Or from a host without a
system_id.)

To benefit fully from system_id, all hosts must have system_id set, and
VGs must have system_id set.  Two hosts should not be assigned the same
system_id.  Doing so defeats the purpose of the 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.

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

.B Unrestricted:
A local VG that has no system_id.  This VG type is unprotected and
accessible to any host.

.B 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.

.B 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.

.B 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.

.B Clustered:
A shared VG with the clustered flag set, and no system_id.  This VG type
is only accessible to hosts using clvmd.

.SS 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:

.TP
.B none
.br

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.

.I lvm.conf
.nf
global {
    system_id_source = "none"
}
.fi

.TP
.B machineid
.br

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

.I lvm.conf
.nf
global {
    system_id_source = "machineid"
}
.fi

.TP
.B uname
.br

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

.I lvm.conf
.nf
global {
    system_id_source = "uname"
}
.fi

.TP
.B lvmlocal
.br

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

.I lvm.conf
.nf
global {
    system_id_source = "lvmlocal"
}
.fi

.I lvmlocal.conf
.nf
local {
    system_id = "example_name"
}
.fi

.TP
.B file
.br

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

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

.LP

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
allow_system_id 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.

.SS allow_system_id

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/allow_system_id.

.I lvmlocal.conf
.nf
local {
    allow_system_id = [ "my_other_name" ]
}
.fi

.SS vgcreate

In vgcreate, a host sets its own system_id in the VG metadata.
To override this and set another system_id:

.B vgcreate --systemid
.I 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.

.SS 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 all VGs to be read
from disk.

.B 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.

.SS 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_sources.  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.

.SS vgchange

If a VG has a system_id, changing it with vgchange requires --force.
vgchange --systemid is accepted just as with vgcreate.

If a host's system_id is changed, the system_id of its own VG's can be
changed to match.  Using allow_system_id is a way to avoid using force
with vgchange.

To move a VG from one host to another, vgexport and vgimport should be
used.

.SS clustered VGs

A "clustered" VG should have no system_id set, allowing multiple hosts to
use it via clvm.  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.

.SS 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.

.SS 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.  Coodination 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.  If the other hosts run a command to rescan
devices, and update lvmetad, they would then recognize the PV has become
used by another host.  A command that rescans devices could be pvscan
--cache, or vgs --foreign.

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