docs/administration-guide.rst

   1 Administration Guide
   2 ====================
   3
   4 The administration guide.
   5
   6
   7 Terminology
   8 -----------
   9
  10 Backup Content
  11 ~~~~~~~~~~~~~~
  12
  13 When doing deduplication, there are different strategies to get
  14 optimal results in terms of performance and/or deduplication rates.
  15 Depending on the type of data, one can split it into fixed or variable
  16 sized chunks.
  17
  18 Fixed sized chunking needs almost no CPU performance, and is used to
  19 backup virtual machine images.
  20
  21 Variable sized chunking needs more CPU power, but is essential to get
  22 good deduplication rates for file archives.
  23
  24 Therefore, the backup server supports both strategies.
  25
  26
  27 File Archives
  28 ^^^^^^^^^^^^^
  29
  30 .. see https://moinakg.wordpress.com/2013/06/22/high-performance-content-defined-chunking/
  31
  32 A file archive stores a whole directory tree. Content is stored using
  33 the :ref:`pxar-format`, split into variable sized chunks. The format
  34 is specially optimized to achieve good deduplication rates.
  35
  36
  37 Image Archives
  38 ^^^^^^^^^^^^^^
  39
  40 This is used for virtual machine images and other large binary
  41 data. Content is split into fixed sized chunks.
  42
  43
  44 Binary Data (BLOBs)
  45 ^^^^^^^^^^^^^^^^^^^
  46
  47 This type is used to store smaller (< 16MB) binaries like
  48 configuration data. Larger files should be stored as image archive.
  49
  50 .. caution:: Please do not store all files as BLOBs. Instead, use the
  51    file archive to store whole directory trees.
  52
  53
  54 Backup Type
  55 ~~~~~~~~~~~
  56
  57 The backup server groups backups by *type*, where *type* is one of:
  58
  59 ``vm``
  60     This type is use for :term:`virtual machine`\ s. Typically
  61     contains the virtual machine configuration and an image archive
  62     for each disk.
  63
  64 ``ct``
  65     This type is use for :term:`container`\ s. Contains the container
  66     configuration and a single file archive for the container content.
  67
  68 ``host``
  69     This type is used for physical host, or if you want to run backup
  70     manually from inside virtual machines or containers. Such backup
  71     may contains file and image archives (no restrictions here).
  72
  73
  74 Backup ID
  75 ~~~~~~~~~
  76
  77 An unique ID. Usually the virtual machine or container ID. ``host``
  78 type backups normally use the hostname.
  79
  80
  81 Backup Time
  82 ~~~~~~~~~~~
  83
  84 The time when the backup was made.
  85
  86
  87 Backup Snapshot
  88 ~~~~~~~~~~~~~~~
  89
  90 We call the triplet ``<type>/<ID>/<time>`` a backup snapshot. It
  91 uniquely identifies a specific backup within a datastore.
  92
  93 .. code-block:: console
  94    :caption: Backup Snapshot Examples
  95
  96     vm/104/2019-10-09T08:01:06Z
  97     host/elsa/2019-11-08T09:48:14Z
  98
  99 As you can see, the time is formatted as RFC3399_ using Coordinated
 100 Universal Time (UTC_, identified by the trailing *Z*).
 101
 102
 103 :term:`DataStore`
 104 ~~~~~~~~~~~~~~~~~
 105
 106 A datastore is a place to store backups. The current implementation
 107 uses a directory inside a standard unix file system (``ext4``, ``xfs``
 108 or ``zfs``) to store backup data.
 109
 110 Datastores are identified by a simple *ID*. You can configure that
 111 when setting up the backup server.
 112
 113
 114 Backup Server Management
 115 ------------------------
 116
 117 The command line tool to configure and manage the server is called
 118 :command:`proxmox-backup-manager`.
 119
 120
 121 Datastore Configuration
 122 ~~~~~~~~~~~~~~~~~~~~~~~
 123
 124 A :term:`datastore` is a place to store backups. You can configure
 125 several datastores, but you need at least one of them. The datastore is identified by a simple `name` and point to a directory.
 126
 127 The following command creates a new datastore called ``store1`` on :file:`/backup/disk1/store1`
 128
 129 .. code-block:: console
 130
 131   # proxmox-backup-manager datastore create store1 /backup/disk1/store1
 132
 133 To list existing datastores use:
 134
 135 .. code-block:: console
 136
 137   # proxmox-backup-manager datastore list
 138   store1 /backup/disk1/store1
 139
 140 Finally, it is also possible to remove the datastore configuration:
 141
 142 .. code-block:: console
 143
 144   # proxmox-backup-manager datastore remove store1
 145
 146 .. note:: Above command removes the datastore configuration. It does
 147    not delete any data from the underlying directory.
 148
 149
 150 File Layout
 151 ^^^^^^^^^^^
 152
 153 .. todo:: Add datastore file layout example
 154
 155
 156 Backup Client usage
 157 -------------------
 158
 159 The command line client is called :command:`proxmox-backup-client`.
 160
 161 Respository Locations
 162 ~~~~~~~~~~~~~~~~~~~~~
 163
 164 The client uses a special repository notation to specify a datastore
 165 on the backup server.
 166
 167   [[username@]server:]datastore
 168
 169 If you do not specify a ``username`` the default is ``root@pam``. The
 170 default for server is to use the local host (``localhost``).
 171
 172 You can pass the repository by setting the ``--repository`` command
 173 line options, or by setting the ``PBS_REPOSITORY`` environment
 174 variable.
 175
 176
 177 Environment Variables
 178 ~~~~~~~~~~~~~~~~~~~~~~
 179
 180 ``PBS_REPOSITORY``
 181   The default backup repository.
 182
 183 ``PBS_PASSWORD``
 184   When set, this value is used for the password required for the
 185   backup server.
 186
 187 ``PBS_ENCRYPTION_PASSWORD``
 188
 189   When set, this value is used to access the secret encryption key (if
 190   protected by password).
 191
 192
 193 Creating Backups
 194 ~~~~~~~~~~~~~~~~
 195
 196
 197 Encryption
 198 ^^^^^^^^^^
 199
 200
 201 Restoring Data
 202 ~~~~~~~~~~~~~~
 203
 204
 205 `Proxmox VE`_ integration
 206 -------------------------
 207
 208
 209 .. include:: command-line-tools.rst
 210
 211 .. include:: services.rst
 212
 213 .. include host system admin at the end
 214
 215 .. include:: sysadmin.rst