1 files changed, 277 insertions, 0 deletions
diff --git a/man/lvmsystemid.7.in b/man/lvmsystemid.7.in
new file mode 100644
index 000000000..d1efee4d9
--- /dev/null
+++ b/man/lvmsystemid.7.in
@@ -0,0 +1,277 @@
+.TH "LVMSYSTEMID" "7" "LVM TOOLS #VERSION#" "Red Hat, Inc" "\""
+
+.SH NAME
+lvmsystemid \(em LVM system id
+
+.SH DESCRIPTION
+
+The system_id is a host identifier that lvm saves in VG metadata to
+identify a host as the owner of the VG.  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 will 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 none.
+
+.I lvm.conf
+.nf
+global {
+    system_id_source = "none"
+}
+.fi
+
+.TP
+.B machineid
+
+The content of /etc/machine-id is used as the system_id.
+
+.I lvm.conf
+.nf
+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.
+
+.I lvm.conf
+.nf
+global {
+    system_id_source = "uname"
+}
+.fi
+
+.TP
+.B lvmlocal
+
+The system_id is defined in lvm-local.conf local/system_id.
+
+.I lvm.conf
+.nf
+global {
+    system_id_source = "lvmlocal"
+}
+.fi
+
+.I lvm-local.conf
+.nf
+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.
+
+.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
+lvm-local.conf local/allow_system_id.
+
+.I lvm-local.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
+
+.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 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 vgchange
+
+If a VG has a system_id, changing it with vgchange requires --force.
+vgchange --systemid and --systemidsource are accepted just as with
+vgcreate.
+
+If a host's system_id is changed, the system_id of its 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 are usually
+the best method.
+
+It is possible to use vgchange to change the owner of a VG.  The first
+approach is to run vgchange on the current owner, changing the system_id
+to match the new owner's system_id.  If this is not possible, a forced
+vgchange from the new owner using its own system_id is possible.
+
+.SS display
+
+The system_id of a vg is displayed with the "systemid" reporting option:
+
+.B vgs -o+systemid
+
+.SS accessibility
+
+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.)
+
+This access restriction applies to all lvm commands with two exceptions:
+
+- Changing the system_id as documented above.
+.br
+- Reporting a VG from disk as documented below.
+
+.SS clustered VGs
+
+A "clustered" VG should have no system_id set, allowing multiple hosts to
+use it.  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 caching
+
+lvmetad on each host caches all visible VGs, including VGs belonging to
+other hosts.  Because each host independently modifies its own VGs, the VG
+metadata cached for other hosts is expected to be out of date.  For this
+reason, a reporting command such as 'vgs' will not by default report
+information about other host's VGs.  (It simply produces the "Cannot
+access" message above, including the VG name and system_id.)
+
+With the special option (?FIXME?), a reporting command like 'vgs' will
+read foreign VGs from disk, rather than from lvmetad, and report all the
+current VG information.  Locally owned VGs are still read from cache.
+
+.SS unresolved questions
+
+either fix or document these issues as limitations:
+
+vgexport/vgimport: to move a VG from hostA to hostB, hostA will run
+vgexport, and hostB will run vgimport.  But, lvmetad on hostB will have
+the old cached copy of the un-exported VG.  So, before running vgimport,
+hostB host should invalidate the cached instance of the VG in lvmetad,
+reread it from disk, and update the lvmetad copy.  This mechanism exists
+already in the lvmlockd patch.  It is fairly short and simple, and can be
+ported to lvm next to use in this case.
+
+vgchange of a system_id has the same issue as vgimport: the locally cached
+vg may not be up to date, and needs to be read from disk before forcibly
+changing the systemid.  (A host changing the system_id of its own vg does
+not have this problem, it's just the force case where you are changing the
+system_id on a VG that doesn't belong to you.  Perhaps we should eliminate
+this forced vgchange and require vgexport/vgimport?)
+
+The FIXME related to reporting a foreign VG by reading from disk instead
+of from cache.  A new option is needed to enable this.  The mechanism can
+be the same as the invalidation mechanism used by vgimport.
+
+How should the presence of foreign vgs affect the exit code of an lvm
+command?  We don't want reporting commands to always fail with foreign vgs
+are visible (see similar issue with ignoreskippedcluster).  Commands to
+modify a foreign VG clearly fail, and should report/exit with error.  If
+the foreign vg is named explicitly in the command, does that help answer
+the question?
+
+When reporting foreign VGs from the cache (the option to read from disk is
+not used), the foreign VG is skipped and not reported.  The command just
+prints a warning:
+"Cannot access VG X with system id Y from local system id Z".
+
+The values X and Y in that warning come from lvmetad and may not be valid
+any longer.  The vg may have been renamed or removed, and the system_id
+may have been changed.  For this reason, the warning may be misleading.
+Perhaps this warning should be removed, and we only display information
+about foreign vgs when the new option is used that reads any foreign vg
+from disk.
+
+
+.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)
+