tsarevvv/proxmox-backup
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
7c1029d760
proxmox-backup/docs/terminology.rst

133 lines
3.6 KiB
ReStructuredText
Raw Normal View History

docs/online-help: prefix some refs with their chapter name and fix some issues from referenced named the same as their heading they anchor too. This should be fixed for real in our python plugin to scan for such references, its probably a bug there, but as most of the problematic ones where wrong (missing chapter prefix) anyway changing them is OK too. Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2021-02-05 13:42:04 +03:00
.. _terms:
docs: explain some technical details about datastores/chunks adds explanations for: * what datastores are * their relation with snapshots/chunks * basic information about chunk directory structures * fixed-/dynamically-sized chunks * special handling of encrypted chunks * hash collision probability * limitation of file-based backups Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
2020-12-11 15:17:09 +03:00
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
Terminology
===========
Backup Content
--------------
When doing deduplication, there are different strategies to get
optimal results in terms of performance and/or deduplication rates.
Depending on the type of data, it can be split into *fixed* or *variable*
sized chunks.
Fixed sized chunking requires minimal CPU power, and is used to
backup virtual machine images.
Variable sized chunking needs more CPU power, but is essential to get
good deduplication rates for file archives.
The Proxmox Backup Server supports both strategies.
Image Archives: ``<name>.img``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is used for virtual machine images and other large binary
data. Content is split into fixed-sized chunks.
File Archives: ``<name>.pxar``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. see https://moinakg.wordpress.com/2013/06/22/high-performance-content-defined-chunking/
A file archive stores a full directory tree. Content is stored using
the :ref:`pxar-format`, split into variable-sized chunks. The format
is optimized to achieve good deduplication rates.
Binary Data (BLOBs)
~~~~~~~~~~~~~~~~~~~
This type is used to store smaller (< 16MB) binary data such as
docs: language and formatting fixup Some minor changes to the sections: Introduction, Installation, Terminology, GUI, Storage, and User Management Mention tape backup in main features Update epilog.rst with link for 'LXC'. Remove FIXME from epilog.rst (I believe this was a note to repair the not-yet-created pbs wiki link). Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2021-10-11 14:11:43 +03:00
configuration files. Larger files should be stored as image archives.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
.. caution:: Please do not store all files as BLOBs. Instead, use the
docs: language and formatting fixup Some minor changes to the sections: Introduction, Installation, Terminology, GUI, Storage, and User Management Mention tape backup in main features Update epilog.rst with link for 'LXC'. Remove FIXME from epilog.rst (I believe this was a note to repair the not-yet-created pbs wiki link). Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2021-10-11 14:11:43 +03:00
file archive to store entire directory trees.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
Catalog File: ``catalog.pcat1``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The catalog file is an index for file archives. It contains
docs: language and formatting fixup Some minor changes to the sections: Introduction, Installation, Terminology, GUI, Storage, and User Management Mention tape backup in main features Update epilog.rst with link for 'LXC'. Remove FIXME from epilog.rst (I believe this was a note to repair the not-yet-created pbs wiki link). Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2021-10-11 14:11:43 +03:00
the list of included files and is used to speed up search operations.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
The Manifest: ``index.json``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
docs: language and formatting fixup Some minor changes to the sections: Introduction, Installation, Terminology, GUI, Storage, and User Management Mention tape backup in main features Update epilog.rst with link for 'LXC'. Remove FIXME from epilog.rst (I believe this was a note to repair the not-yet-created pbs wiki link). Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2021-10-11 14:11:43 +03:00
The manifest contains a list of all backed up files, and their
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
sizes and checksums. It is used to verify the consistency of a
backup.
docs: terminology: add namespaces and slightly restructure Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2022-05-16 16:28:00 +03:00
Backup Namespace
----------------
Namespaces allow for the reuse of a single chunk store deduplication domain for
multiple sources, while avoiding naming conflicts and getting more fine-grained
access control.
Essentially they're implemented as simple directory structure and need no
separate configuration.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
Backup Type
-----------
The backup server groups backups by *type*, where *type* is one of:
``vm``
docs: use case-matching keys for glossary this silences warnings a la: ``` WARNING: term container not found in case sensitive match.made a reference to Container instead ``` the issue is purely cosmetic during build, and should vanish in a newer version of sphinx-doc [0]. [0] https://github.com/sphinx-doc/sphinx/issues/7636 Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
2022-05-16 19:27:30 +03:00
This type is used for :term:`virtual machine<Virtual machine>`\ s. It
typically consists of the virtual machine's configuration file and an image
archive for each disk.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
``ct``
docs: use case-matching keys for glossary this silences warnings a la: ``` WARNING: term container not found in case sensitive match.made a reference to Container instead ``` the issue is purely cosmetic during build, and should vanish in a newer version of sphinx-doc [0]. [0] https://github.com/sphinx-doc/sphinx/issues/7636 Signed-off-by: Stoiko Ivanov <s.ivanov@proxmox.com>
2022-05-16 19:27:30 +03:00
This type is used for :term:`container<Container>`\ s. It consists of the
container's configuration and a single file archive for the filesystem's
contents.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
``host``
docs: language and formatting fixup Some minor changes to the sections: Introduction, Installation, Terminology, GUI, Storage, and User Management Mention tape backup in main features Update epilog.rst with link for 'LXC'. Remove FIXME from epilog.rst (I believe this was a note to repair the not-yet-created pbs wiki link). Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2021-10-11 14:11:43 +03:00
This type is used for file/directory backups created from within a machine.
Typically this would be a physical host, but could also be a virtual machine
or container. Such backups may contain file and image archives; there are no
restrictions in this regard.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
Backup ID
---------
docs: fix some typos The s/Namesapce/Namespace/ one was reported in the forum [0] and so I figured I do a quick scan for others too using codespell. [0]: https://forum.proxmox.com/threads/109724/post-472744 Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2022-05-26 14:08:51 +03:00
A unique ID for a specific Backup Type and Backup Namespace. Usually the
docs: terminology: add namespaces and slightly restructure Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2022-05-16 16:28:00 +03:00
virtual machine or container ID. ``host`` type backups normally use the
hostname.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
Backup Time
-----------
docs: terminology: add namespaces and slightly restructure Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2022-05-16 16:28:00 +03:00
The time when the backup was made with second resolution.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
Backup Group
------------
docs: terminology: add namespaces and slightly restructure Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2022-05-16 16:28:00 +03:00
The tuple ``<type>/<id>`` is called a backup group. Such a group may contain
one or more backup snapshots.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
docs/online-help: prefix some refs with their chapter name and fix some issues from referenced named the same as their heading they anchor too. This should be fixed for real in our python plugin to scan for such references, its probably a bug there, but as most of the problematic ones where wrong (missing chapter prefix) anyway changing them is OK too. Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2021-02-05 13:42:04 +03:00
.. _term_backup_snapshot:
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
Backup Snapshot
---------------
The triplet ``<type>/<ID>/<time>`` is called a backup snapshot. It
docs: terminology: update snapshot uniqueness for namespaces since we introduced namespaces, a snapshot does not have be unique across the datastore anymore, only a namespace. Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
2022-08-26 11:09:19 +03:00
uniquely identifies a specific backup within a namespace.
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
.. code-block:: console
:caption: Backup Snapshot Examples
vm/104/2019-10-09T08:01:06Z
host/elsa/2019-11-08T09:48:14Z
tape, docs, api: fix miscellaneous typos Signed-off-by: Stefan Sterz <s.sterz@proxmox.com> Signed-off-by: Thomas Lamprecht <t.lamprecht@proxmox.com>
2022-03-10 17:10:32 +03:00
As you can see, the time format is RFC3339_ with Coordinated
Restructure docs (more first level headings) This removes the "Backup Management" first level heading in the docs, and either uses the sub headings contained within it as first level headings, or groups previous sections logically under new headings. The administration-guide.rst file is also removed. Its contents are instead separated into various files, that relate to their respective first level heading. Signed-off-by: Dylan Whyte <d.whyte@proxmox.com>
2020-10-02 17:12:57 +03:00
Universal Time (UTC_, identified by the trailing *Z*).
Reference in New Issue Copy Permalink