1 files changed, 200 insertions, 0 deletions
diff --git a/man/lvmsystemid.7.in b/man/lvmsystemid.7.in
new file mode 100644
index 000000000..cb6c0b36e
--- /dev/null
+++ b/man/lvmsystemid.7.in
@@ -0,0 +1,200 @@
+.TH "LVMSYSTEMID" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\""
+
+.SH NAME
+lvmsystemid \(em LVM system id
+
+.SH DESCRIPTION
+
+The lvm system_id is a host identifier used by lvm to identify a VG owner.
+vgcreate includes the local system_id in the metadata of a new VG.  This
+means the host that creates a VG becomes the VG's owner.  lvm commands
+will not operate on a VG owned by another host.
+
+A VG without a system_id can be used by any host, and a host without a
+system_id can use any VG (even a VG with a system_id set).  This can lead
+to mistakes if a VG is visible to multiple hosts at once.
+
+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.
+
+.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 should use to find the
+local system_id:
+
+.TP
+.B none
+
+lvm will not use a system_id.  It will be allowed to access all VGs, and
+will create new VGs without a system_id.  An undefined system_id_source is
+equivalent to system_id_source = "none".
+
+.nf
+lvm.conf
+global {
+    system_id_source = "none"
+}
+.fi
+
+.TP
+.B machineid
+
+The content of /etc/machine-id is used as the system_id.
+
+.nf
+lvm.conf
+global {
+    system_id_source = "machineid"
+}
+.fi
+
+.TP
+.B uname
+
+The string utsname.nodename from
+.BR uname (2)
+is used as the system_id.  A uname of "localhost" is ignored.
+
+.nf
+lvm.conf
+global {
+    system_id_source = "uname"
+}
+.fi
+
+.TP
+.B lvmlocal
+
+The system_id is defined in lvm-local.conf local/system_id.
+
+.nf
+lvm.conf
+global {
+    system_id_source = "lvmlocal"
+}
+
+lvm-local.conf
+local {
+    system_id = "example_name"
+}
+.fi
+
+.TP
+.B file
+
+The system_id is defined in a file specified by lvm.conf
+global/system_id_file.
+
+.nf
+lvm.conf
+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
+lvm-local.conf local/allow_system_id.
+
+.nf
+lvm-local.conf
+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
+
+.B vgcreate --systemidsource
+.I SystemIDSource VG Devices
+
+.I SystemIDSource
+can be a method recognized by lvm.conf system_id_source
+(none, file, lvmlocal, machineid, uname).
+
+Overriding the system_id in either way makes it possible for a host to
+create a VG that it may not be able to use.
+
+.SS vgchange
+
+If a VG has system_id set, changing it with vgchange requires --force.
+vgchange --systemid and --systemidsource are accepted just as with
+vgcreate.
+
+.SS vgexport/vgimport
+
+vgexport clears the system_id.
+
+vgimport sets the VG system_id to the local system_id as determined by
+lvm.conf system_id_sources.
+
+.SS display
+
+The system_id of a vg is displayed with the "systemid" reporting option:
+
+.B vgs -o+systemid
+
+.SS validation
+
+When lvm reads a VG and finds that the VG's system_id does not match
+the local system_id, it will print a warning and not access the VG
+further:
+
+.nf
+Cannot access VG "vg" with system id "x" from local system id "y"
+.fi
+
+To silence these warnings, set lvm.conf log/silent_other_systemid = 1
+(or use a filter to exclude the foreign system's VG.)
+
+.SS clustered VGs
+
+A "clustered" VG should have no system_id set, allowing multiple hosts to
+use it, or it should have a system_id set to a value that multiple hosts
+have added to their allow_system_id list.
+
+.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.
+
+.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)
+