ff971aefc0
The new_backup_provider() method can be used by storage plugins for external backup providers. If the method returns a provider, Proxmox VE will use callbacks to that provider for backups and restore instead of using its usual backup/restore mechanisms. The backup provider API is split into two parts, both of which again need different implementations for VM and LXC guests: 1. Backup API In Proxmox VE, a backup job consists of backup tasks for individual guests. There are methods for initialization and cleanup of the job, i.e. job_init() and job_cleanup() and for each guest backup, i.e. backup_init() and backup_cleanup(). The backup_get_mechanism() method is used to decide on the backup mechanism. Currently, 'file-handle' or 'nbd' for VMs, and 'directory' for containers is possible. The method also let's the plugin indicate whether to use a bitmap for incremental VM backup or not. It is enough to implement one mechanism for VMs and one mechanism for containers. Next, there are methods for backing up the guest's configuration and data, backup_vm() for VM backup and backup_container() for container backup, with the latter running Finally, some helpers like getting the provider name or volume ID for the backup target, as well as for handling the backup log. The backup transaction looks as follows: First, job_init() is called that can be used to check backup server availability and prepare the connection. Then for each guest backup_init() followed by backup_vm() or backup_container() and finally backup_cleanup(). Afterwards job_cleanup() is called. For containers, there is an additional backup_container_prepare() call while still privileged. The actual backup_container() call happens as the (unprivileged) container root user, so that the file owner and group IDs match the container's perspective. 1.1 Backup Mechanisms VM: Access to the data on the VM's disk from the time the backup started is made available via a so-called "snapshot access". This is either the full image, or in case a bitmap is used, the dirty parts of the image since the last time the bitmap was used for a successful backup. Reading outside of the dirty parts will result in an error. After backing up each part of the disk, it should be discarded in the export to avoid unnecessary space usage on the Proxmox VE side (there is an associated fleecing image). VM mechanism 'file-handle': The snapshot access is exposed via a file descriptor. A subroutine to read the dirty regions for incremental backup is provided as well. VM mechanism 'nbd': The snapshot access and, if used, bitmap are exported via NBD. Container mechanism 'directory': A copy or snapshot of the container's filesystem state is made available as a directory. The method is executed inside the user namespace associated to the container. 2. Restore API The restore_get_mechanism() method is used to decide on the restore mechanism. Currently, 'qemu-img' for VMs, and 'directory' or 'tar' for containers are possible. It is enough to implement one mechanism for VMs and one mechanism for containers. Next, methods for extracting the guest and firewall configuration and the implementations of the restore mechanism via a pair of methods: an init method, for making the data available to Proxmox VE and a cleanup method that is called after restore. 2.1. Restore Mechanisms VM mechanism 'qemu-img': The backup provider gives a path to the disk image that will be restored. The path needs to be something 'qemu-img' can deal with, e.g. can also be an NBD URI or similar. Container mechanism 'directory': The backup provider gives the path to a directory with the full filesystem structure of the container. Container mechanism 'tar': The backup provider gives the path to a (potentially compressed) tar archive with the full filesystem structure of the container. See the PVE::BackupProvider::Plugin module for the full API documentation. Signed-off-by: Fiona Ebner <f.ebner@proxmox.com> [WB: replace backup_vm_available_bitmaps with backup_vm_query_incremental, which instead of a bitmap name provides a bitmap mode that is 'new' (create or *recreate* a bitmap) or 'use' (use an existing bitmap, or create one if none exists)] Signed-off-by: Wolfgang Bumiller <w.bumiller@proxmox.com> Tested-by: Wolfgang Bumiller <w.bumiller@proxmox.com> Reviewed-by: Wolfgang Bumiller <w.bumiller@proxmox.com> Link: https://lore.proxmox.com/20250404133204.239783-5-f.ebner@proxmox.com