doc/ceph-volume create the systemd lvm reference

Signed-off-by: Alfredo Deza <adeza@redhat.com>

diff --git a/doc/ceph-volume/lvm/systemd.rst b/doc/ceph-volume/lvm/systemd.rst
new file mode 100644 (file)
index 0000000..7162e04
--- /dev/null
+++ b/doc/ceph-volume/lvm/systemd.rst
@@ -0,0 +1,46 @@
+.. _ceph-volume-systemd:
+
+systemd
+=======
+As part of the :ref:`ceph-volume-lvm-activate` process, a few systemd units will get enabled
+that will use the OSD id and uuid as part of their name. These units will be
+run when the system boots, and will proceed to activate their corresponding
+volumes.
+
+The API for activation requires both the :term:`OSD id` and :term:`OSD uuid`,
+which get persisted by systemd. Internally, the activation process enables the
+systemd unit using the following convention::
+
+    ceph-volume@<type>-<extra metadata>
+
+Where ``type`` is the sub-command used to parse the extra metadata, and ``extra
+metadata`` is any additional information needed by the sub-command to be able
+to activate the OSD. For example an OSD with an ID of 0, for the ``lvm``
+sub-command would look like::
+
+    systemctl enable ceph-volume@lvm-0-0A3E1ED2-DA8A-4F0E-AA95-61DEC71768D6
+
+
+Process
+-------
+The systemd unit is a :term:`systemd oneshot` service, meant to start at boot after the
+local filesystem is ready to be used.
+
+Upon startup, it will identify the logical volume using :term:`LVM tags`,
+finding a matching ID and later ensuring it is the right one with
+the :term:`OSD uuid`.
+
+After identifying the correct volume it will then proceed to mount it by using
+the OSD destination conventions, that is::
+
+    /var/lib/ceph/osd/<cluster name>-<osd id>
+
+For our example OSD with an id of ``0``, that means the identified device will
+be mounted at::
+
+
+    /var/lib/ceph/osd/ceph-0
+
+Once that process is complete, a call will be made to start the OSD::
+
+    systemctl start ceph-osd@0

diff --git a/doc/dev/ceph-volume/systemd.rst b/doc/dev/ceph-volume/systemd.rst
index 52811fe4599fad1b8d4501fa74c354036ae44bdd..8553430ee0d821d5ec1f73d5384cbf354f4c5aa8 100644 (file)
--- a/doc/dev/ceph-volume/systemd.rst
+++ b/doc/dev/ceph-volume/systemd.rst
@@ -1,4 +1,4 @@
-.. _ceph-volume-systemd:
+.. _ceph-volume-systemd-api:
 
 systemd
 =======
@@ -7,23 +7,23 @@ ability to persist information as a suffix to the instance name.
 
 ``ceph-volume`` exposes the following convention for unit files::
 
-    ceph-volume@<osd id>-<osd uuid>-<device type>
+    ceph-volume@<sub command>-<extra metadata>
 
-For example, this is how enabling an OSD could look like using the :doc:`lvm
-<lvm/lvm>` sub command::
+For example, this is how enabling an OSD could look like for the 
+:ref:`ceph-volume-lvm` sub command::
 
-    systemctl enable ceph-volume@0-8715BEB4-15C5-49DE-BA6F-401086EC7B41-lvm
+    systemctl enable ceph-volume@lvm-0-8715BEB4-15C5-49DE-BA6F-401086EC7B41
 
 
-These 3 pieces of persisted information are needed by the systemd unit so that
-it understands what OSD it needs to activate along with the related sub
-command. Since ``lvm`` is not the only subcommand that will be supported, this
+These 3 pieces of persisted information are needed by the sub-command so that
+it understands what OSD it needs to activate.
+
+Since ``lvm`` is not the only subcommand that will be supported, this
 is how it will allow other device types to be defined.
 
 At some point for example, for plain disks, it could be::
 
-    systemctl enable ceph-volume@0-8715BEB4-15C5-49DE-BA6F-401086EC7B41-disk
-
+    systemctl enable ceph-volume@disk-0-8715BEB4-15C5-49DE-BA6F-401086EC7B41
 
 At startup, the systemd unit will execute a helper script that will parse the
 suffix and will end up calling ``ceph-volume`` back. Using the previous