pve-storage-pbs.adoc

   1 [[storage_pbs]]
   2 Proxmox Backup Server
   3 ---------------------
   4 ifdef::wiki[]
   5 :pve-toplevel:
   6 :title: Storage: Proxmox Backup Server
   7 endif::wiki[]
   8
   9 Storage pool type: `pbs`
  10
  11 This backend allows direct integration of a Proxmox Backup Server into {pve}
  12 like any other storage.
  13 A Proxmox Backup storage can be added directly through the {pve} API, CLI or
  14 the web interface.
  15
  16 Configuration
  17 ~~~~~~~~~~~~~
  18
  19 The backend supports all common storage properties, except the shared flag,
  20 which is always set. Additionally, the following special properties to Proxmox
  21 Backup Server are available:
  22
  23 server::
  24
  25 Server IP or DNS name. Required.
  26
  27 port::
  28
  29 Use this port instead of the default one, i.e. `8007`. Optional.
  30
  31 username::
  32
  33 The username for the Proxmox Backup Server storage. Required.
  34
  35 TIP: Do not forget to add the realm to the username. For example, `root@pam` or
  36 `archiver@pbs`.
  37
  38 password::
  39
  40 The user password. The value will be saved in a file under
  41 `/etc/pve/priv/storage/<STORAGE-ID>.pw` with access restricted to the root
  42 user. Required.
  43
  44 datastore::
  45
  46 The ID of the Proxmox Backup Server datastore to use. Required.
  47
  48 fingerprint::
  49
  50 The fingerprint of the Proxmox Backup Server API TLS certificate. You can get
  51 it in the Servers Dashboard or using the `proxmox-backup-manager cert info`
  52 command. Required for self-signed certificates or any other one where the host
  53 does not trusts the servers CA.
  54
  55 encryption-key::
  56
  57 A key to encrypt the backup data from the client side. Currently only
  58 non-password protected (no key derive function (kdf)) are supported. Will be
  59 saved in a file under `/etc/pve/priv/storage/<STORAGE-ID>.enc` with access
  60 restricted to the root user.  Use the magic value `autogen` to automatically
  61 generate a new one using `proxmox-backup-client key create --kdf none <path>`.
  62 Optional.
  63
  64 master-pubkey::
  65
  66 A public RSA key used to encrypt the backup encryption key as part of the
  67 backup task. The encrypted copy will be appended to the backup and stored on
  68 the Proxmox Backup Server instance for recovery purposes.
  69 Optional, requires `encryption-key`.
  70
  71 .Configuration Example (`/etc/pve/storage.cfg`)
  72 ----
  73 pbs: backup
  74         datastore main
  75         server enya.proxmox.com
  76         content backup
  77         fingerprint 09:54:ef:..snip..:88:af:47:fe:4c:3b:cf:8b:26:88:0b:4e:3c:b2
  78         prune-backups keep-all=1
  79         username archiver@pbs
  80 ----
  81
  82 Storage Features
  83 ~~~~~~~~~~~~~~~~
  84
  85 Proxmox Backup Server only supports backups, they can be block-level or
  86 file-level based. {pve} uses block-level for virtual machines and file-level for
  87 container.
  88
  89 .Storage features for backend `pbs`
  90 [width="100%",cols="m,4*d",options="header"]
  91 |===============================================================
  92 |Content types |Image formats |Shared |Snapshots |Clones
  93 |backup        |n/a           |yes    |n/a       |n/a
  94 |===============================================================
  95
  96 [[storage_pbs_encryption]]
  97 Encryption
  98 ~~~~~~~~~~
  99
 100 [thumbnail="screenshot/storage-pbs-encryption-with-key.png"]
 101
 102 Optionally, you can configure client-side encryption with AES-256 in GCM mode.
 103 Encryption can be configured either via the web interface, or on the CLI with
 104 the `encryption-key` option (see above). The key will be saved in the file
 105 `/etc/pve/priv/storage/<STORAGE-ID>.enc`, which is only accessible by the root
 106 user.
 107
 108 WARNING: Without their key, backups will be inaccessible. Thus, you should
 109 keep keys ordered and in a place that is separate from the contents being
 110 backed up. It can happen, for example, that you back up an entire system, using
 111 a key on that system. If the system then becomes inaccessible for any reason
 112 and needs to be restored, this will not be possible as the encryption key will be
 113 lost along with the broken system.
 114
 115 It is recommended that you keep your key safe, but easily accessible, in
 116 order for quick disaster recovery. For this reason, the best place to store it
 117 is in your password manager, where it is immediately recoverable. As a backup to
 118 this, you should also save the key to a USB flash drive and store that in a secure
 119 place. This way, it is detached from any system, but is still easy to recover
 120 from, in case of emergency. Finally, in preparation for the worst case scenario,
 121 you should also consider keeping a paper copy of your key locked away in a safe
 122 place. The `paperkey` subcommand can be used to create a QR encoded version of
 123 your key. The following command sends the output of the `paperkey` command to
 124 a text file, for easy printing.
 125
 126 ----
 127 # proxmox-backup-client key paperkey /etc/pve/priv/storage/<STORAGE-ID>.enc --output-format text > qrkey.txt
 128 ----
 129
 130 Additionally, it is possible to use a single RSA master key pair for key
 131 recovery purposes: configure all clients doing encrypted backups to use a
 132 single public master key, and all subsequent encrypted backups will contain a
 133 RSA-encrypted copy of the used AES encryption key. The corresponding private
 134 master key allows recovering the AES key and decrypting the backup even if the
 135 client system is no longer available.
 136
 137 WARNING: The same safe-keeping rules apply to the master key pair as to the
 138 regular encryption keys. Without a copy of the private key recovery is not
 139 possible! The `paperkey` command supports generating paper copies of private
 140 master keys for storage in a safe, physical location.
 141
 142 Because the encryption is managed on the client side, you can use the same
 143 datastore on the server for unencrypted backups and encrypted backups, even
 144 if they are encrypted with different keys. However, deduplication between
 145 backups with different keys is not possible, so it is often better to create
 146 separate datastores.
 147
 148 NOTE: Do not use encryption if there is no benefit from it, for example, when
 149 you are running the server locally in a trusted network. It is always easier to
 150 recover from unencrypted backups.
 151
 152 Example: Add Storage over CLI
 153 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 154
 155 // TODO: FIXME: add once available
 156 //You can get a list of exported CIFS shares with:
 157 //
 158 //----
 159 //# pvesm scan pbs <server> [--username <username>] [--password]
 160 //----
 161
 162 Then you could add this share as a storage to the whole {pve} cluster
 163 with:
 164
 165 ----
 166 # pvesm add pbs <id> --server <server> --datastore <datastore> --username <username> --fingerprint 00:B4:... --password
 167 ----
 168
 169 ifdef::wiki[]
 170
 171 See Also
 172 ~~~~~~~~
 173
 174 * link:/wiki/Storage[Storage]
 175
 176 endif::wiki[]