From 3eba9d5d9bde30463404c517b7bb16c0dde6bfcb Mon Sep 17 00:00:00 2001
From: Thomas Kluyver <thomas@kluyver.me.uk>
Date: Fri, 29 Oct 2021 18:24:11 +0000
Subject: [PATCH] Describe where machine ID comes from

---
 doc/dbus-specification.xml | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/doc/dbus-specification.xml b/doc/dbus-specification.xml
index 31a351dd0..585182160 100644
--- a/doc/dbus-specification.xml
+++ b/doc/dbus-specification.xml
@@ -4245,6 +4245,24 @@
         It does not matter which object path a GetMachineId is sent to.  The
         reference implementation handles this method automatically.
       </para>
+      <para>
+        On Unix, implementations should try to read the machine ID from
+        <literal>/var/lib/dbus/machine-id</literal> and
+        <literal>/etc/machine-id</literal>. The latter is
+        <ulink url='https://www.freedesktop.org/software/systemd/man/machine-id.html'>
+        defined by systemd</ulink>, but systems not using systemd may provide
+        an equivalent file.
+        If both exist, they are expected to have the same contents, and if they
+        differ, the spec does not define which takes precedence (the reference
+        implementation prefers <literal>/var/lib/dbus/machine-id</literal>,
+        but sd-bus does not).
+      </para>
+      <para>
+        On Windows, the hardware profile GUID is used as the machine ID,
+        with the punctuation removed. This can be obtained with the
+        <ulink url='https://docs.microsoft.com/en-us/windows/win32/api/winbase/nf-winbase-getcurrenthwprofilea'>
+        <function>GetCurrentHwProfile</function></ulink> function.
+      </para>
       <para>
         The UUID is intended to be per-instance-of-the-operating-system, so may represent
         a virtual machine running on a hypervisor, rather than a physical machine.
-- 
2.47.3