From fea8789cbac0bcf9de3c6c1ad9a12b7371b40989 Mon Sep 17 00:00:00 2001
From: Dietmar Maurer <dietmar@proxmox.com>
Date: Sun, 17 Nov 2019 09:28:38 +0100
Subject: [PATCH] docs/administration-guide.rst: add section termonology

---
 docs/administration-guide.rst | 69 +++++++++++++++++++++++++++++++++++
 docs/epilog.rst               |  3 ++
 2 files changed, 72 insertions(+)

diff --git a/docs/administration-guide.rst b/docs/administration-guide.rst
index 91124418..3463bac7 100644
--- a/docs/administration-guide.rst
+++ b/docs/administration-guide.rst
@@ -4,6 +4,69 @@ Administration Guide
 The administartion guide.
 
 
+Terminology
+-----------
+
+Backup Type
+~~~~~~~~~~~
+
+The backup server groups backups by *type*, where *type* is one of:
+
+``vm``
+    This type is use for :term:`virtual machine`\ s. Typically
+    contains the virtual machine configuration and an image archive
+    for each disk.
+
+``ct``
+    This type is use for :term:`container`\ s. Contains the container
+    configuration and a single file archive for the container content.
+
+``host``
+    This type is used for physical host, or if you want to run backup
+    manually from inside virtual machines or containers. Such backup
+    may contains file and image archives (no restrictions here).
+
+
+Backup ID
+~~~~~~~~~
+
+An unique ID. Usually the virtual machine or container ID. ``host``
+type backups normally use the hostname.
+
+
+Backup Time
+~~~~~~~~~~~
+
+The time when the backup was made.
+
+
+Backup Snapshot
+~~~~~~~~~~~~~~~
+
+We call the triplet ``<type>/<ID>/<time>`` a backup snapshot. It
+uniquely identifies a specific backup within a datastore.
+
+.. code-block:: console
+   :caption: Backup Snapshot Examples
+
+    vm/104/2019-10-09T08:01:06Z
+    host/elsa/2019-11-08T09:48:14Z
+
+As you can see, the time is formatted as RFC3399_ using Coordinated
+Universal Time (UTC_, identified by the trailing *Z*).
+
+
+:term:`DataStore`
+~~~~~~~~~~~~~~~~~
+
+A datastore is a place to store backups. The current implementation
+uses a directory inside a standard unix file system (``ext4``, ``xfs``
+or ``zfs``) to store backup data.
+
+Datastores are identified by a simple *ID*. You can configure that
+when setting up the backup server.
+
+
 Backup Server Management
 ------------------------
 
@@ -40,6 +103,12 @@ Finally, it is also possible to remove the datastore configuration:
    not delete any data from the underlying directory.
 
 
+File Layout
+^^^^^^^^^^^
+
+.. todo:: Add datastore file layout example
+
+
 Backup Client usage
 -------------------
 
diff --git a/docs/epilog.rst b/docs/epilog.rst
index eaab67a2..c1de7e09 100644
--- a/docs/epilog.rst
+++ b/docs/epilog.rst
@@ -31,3 +31,6 @@
 .. _LVM: https://en.wikipedia.org/wiki/Logical_Volume_Manager_(Linux)
 .. _ZFS: https://en.wikipedia.org/wiki/ZFS
 .. _Proxmox VE: https://pve.proxmox.com
+
+.. _RFC3399: https://tools.ietf.org/html/rfc3339
+.. _UTC: https://en.wikipedia.org/wiki/Coordinated_Universal_Time