In our previous tutorial titled "Getting Started with Proxmox Backup Server", we discussed how to backup and restore Proxmox VMs and Containers. Today, we will learn how to create file level backups using Proxmox Backup Client application. Proxmox Backup Client comes in handy when you want to backup certain files instead of backing up the whole VM or Container. It also can be useful when you want to backup files from non-VMs or non-Containers (i.e. a physical machine).
Table of Contents
What is Proxmox Backup Client?
Proxmox Backup Client is just a command line client for Proxmox Backup Server. Using Proxmox Backup Client, we can create a backup from within the machine. This can be a physical host, a virtual machine, or a container.
Install Proxmox Backup Client
Go to the client machine where you want to install Proxmox Backup Client application. For the purpose of this guide, I will be using Debian 11 bullseye system.
Add the official Proxmox Client repository. The official repository is available for Debian, Ubuntu and its derivatives.
First, add the Proxmox GPG key using command:
$ sudo wget https://enterprise.proxmox.com/debian/proxmox-release-bullseye.gpg -O /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
Verify the SHA512 checksum using command:
$ sha512sum /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
You should get an output like below:
7fb03ec8a1675723d2853b84aa4fdb49a46a3bb72b9951361488bfd19b29aab0a789a4f8c7406e71a69aabbc727c936d3549731c4659ffa1a08f44db8fdcebfa /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
And then, verify md5sum:
$ md5sum /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg bcc35c7173e0845c0d6ad6470b70f50e /etc/apt/trusted.gpg.d/proxmox-release-bullseye.gpg
If you got same output as above, you're good to go!
Now, let us add Proxmox Backup Client repository in the Debian client system.
Create a file /etc/apt/sources.list.d/pbs-client.list :
$ sudo nano /etc/apt/sources.list.d/pbs-client.list
Add the following snippet:
deb http://download.proxmox.com/debian/pbs-client bullseye main
On Debian buster and Ubuntu 20.04 systems, add the following line in file /etc/apt/sources.list.d/pbs-client.list.
deb http://download.proxmox.com/debian/pbs-client buster main
Save the file and close it by pressing CTRL+O followed by CTRL+X.
Update the repository list using command:
$ sudo apt update
Finally, install Proxmox Backup Client using command:
$ sudo apt install proxmox-backup-client
For Fedora, RHEL-based systems, there is add a third-party Proxmox Backup Client repository available.
To enable this copr repo, run the following command as root or sudo user:
$ sudo dnf copr enable derenderkeks/proxmox-backup-client
Now you can install the proxmox-backup-client package:
$ sudo dnf install proxmox-backup-client
For EL8 and EL9 systems, download the respective repository from this page and install Proxmox Backup Client.
Backup Files Using Proxmox Backup Client
Make sure you know the correct login credentials and the repository name of the Proxmox Backup Server. For the purpose of this guide, I am going to backup files from a Debian 11 client to my Proxmox Backup Server.
As stated already, the machine need not to be a VM or Container. We can backup files from either physical or virtual machine or containers using Proxmox Backup Client.
For testing purpose, I am going to create a simple text file in my Debian 11 client machine.
$ echo "Backup my files to PBS" > ostechnix_backup.txt
Now let us backup the entire root file system of the Debian 11 client to "backups" datastore of PBS.
To do so, switch to "root" user:
$ sudo su -
And backup the entire root filesystem to PBS using command:
# proxmox-backup-client backup root.pxar:/ --repository 192.168.1.200:backups
The above command will create a file archive named root.pxar containing all the files in the / directory and then upload the root.pxar file to the "backups" datastore in the PBS.
Type the root password of your Proxmox Backup Server and press 'y' twice to continue. Once the backup is successful, you will see the summary of the backup such as the backup size and how long it took to backup etc.
Password for "root@pam": ******* Starting backup: host/Debian11CT/2023-02-21T10:10:07Z Client name: Debian11CT Starting backup protocol: Tue Feb 21 10:10:12 2023 fingerprint: 88:35:ef:e4:82:c8:97:99:77:2b:10:64:83:3c:5a:76:81:de:11:db:57:46:3a:38:f7:43:b0:a1:d8:c0:c2:2b Are you sure you want to continue connecting? (y/n): y fingerprint: 88:35:ef:e4:82:c8:97:99:77:2b:10:64:83:3c:5a:76:81:de:11:db:57:46:3a:38:f7:43:b0:a1:d8:c0:c2:2b Are you sure you want to continue connecting? (y/n): y No previous manifest available. Upload directory '/' to '192.168.1.200:backups' as root.pxar.didx skipping mount point: "dev" failed to open file: "lost+found": access denied skipping mount point: "proc" skipping mount point: "run" skipping mount point: "sys" root.pxar: had to backup 2.535 GiB of 2.541 GiB (compressed 1.053 GiB) in 18.86s root.pxar: average backup speed: 137.631 MiB/s root.pxar: backup was done incrementally, reused 6.004 MiB (0.2%) Uploaded backup catalog (1.062 MiB) Duration: 19.52s End Time: Tue Feb 21 10:10:32 2023
Let us verify if the backup is really done.
Verify Backups
Go to your PBS Dashboard and click the datastore (e.g. backups) where you send the backup earlier and then click the "Content" tab. In my case, I sent the backup to "backups" datastore.
Did you remember Proxmox Backup Server's naming strategy for backups? It usually saves the virtual machine as "vm/vm-id". For instance, I have backed up a VM that has ID 106, so it saves the VM as vm/106. As you already know, vm stands for Virtual machine. Similarly, PBS will save the Containers as "ct/container-id" e.g. ct/100. Here, ct stands for container.
Likewise, PBS will save the individual host's backup with name "host/hostname". As you see in the screenshot below, PBS saved the backup of my Debian 11 container system with name "host/Debian11CT".
View the Contents of Backups
To view and verify the contents of a backup, simply click the on the backup name and expand it by clicking on the + (plus) sign. You will see the individual components of the backup. Select the root.pxar.didx file and click the Browse icon.
Now you will see the actual contents of the root filesystem of the client system. Navigate to the "home" directory and check if all contents are available there.
Did you remember that I created a text file called "ostechnix_backup.txt" earlier? It is the file that you see in the above screenshot. You can simply choose that file and hit "Download" button to download it.
Create Environment Variable
As you may noticed, we had to type a line --repository PBS_Server_IP:datastore (e.g. --repository 192.168.1.200:backups) every time to backup files. This makes the command bit longer. If you want to avoid this, you can set an environment variable for the above line as shown below.
# export PBS_REPOSITORY=192.168.1.200:backups
Edit your .bashrc or whatever your profile file using a text editor:
# nano .bashrc
Add the environment variable:
export PBS_REPOSITORY=192.168.1.200:backups
Replace the IP address and datastore values with your own.
Press CTRL+O followed by CTRL+X to save the file and exit. Log out and log back in to update the changes. Alternatively, you can source the .bashrc file to take effect the changes immediately:
# source .bashrc
From now on, you don't have to type the whole "--repository.." line. You can execute all commands without having to specify the --repository option like below.
# proxmox-backup-client backup root.pxar:/
Did you notice? I didn't specify the --repository parameter in the above command. Because, the --repository value will be retrieved from the environment variable.
Now go back to the PBS dashboard and check if a new backup is created.
As you can see, there is a new backup with a new timestamp in the name (i.e. host/Debian11CT/2023-02-21T12:15:33Z) is created. Whenever you run the proxmox-backup-client backup command, a new backup with current timestamp will be created. By looking at the timestamps, you can easily find which one is the new backup.
Create Encrypted Backups
Proxmox Backup supports client-side encryption with AES-256 encryption method.
Before creating encrypted backups, we need to first create an encryption key using the following command:
# proxmox-backup-client key create my-backup.key
Enter a password twice for the encryption key:
Encryption Key Password: ****** Verify Password: ******
The key will be saved in the current working directory. In our case, it is /root/my-backup.key.
Now, create an encrypted backup of /etc directory, by passing the --keyfile parameter, with the path to the key file like below.
# proxmox-backup-client backup etc.pxar:/etc --keyfile /root/my-backup.key
Enter the root user password of the Proxmox Backup Server and then enter the password for the encryption key.
Password for "root@pam": ******* Starting backup: host/Debian11CT/2023-02-22T10:47:12Z Client name: Debian11CT Starting backup protocol: Wed Feb 22 10:47:18 2023 Using encryption key from '/root/my-backup.key'.. Encryption Key Password: ****** Encryption key fingerprint: 00:f2:7d:a5:d4:df:66:67 Downloading previous manifest (Tue Feb 21 12:15:33 2023) Upload directory '/etc' to '192.168.1.200:backups' as etc.pxar.didx Error downloading .didx from previous manifest: Unable to open dynamic index "/mnt/datastore/backups/host/Debian11CT/2023-02-21T12:15:33Z/etc.pxar.didx" - No such file or directory (os error 2) etc.pxar: had to backup 1.616 MiB of 1.616 MiB (compressed 402.398 KiB) in 0.05s etc.pxar: average backup speed: 34.494 MiB/s Uploaded backup catalog (17.71 KiB) Duration: 5.83s End Time: Wed Feb 22 10:47:24 2023
Please note that if you do not specify the name of the backup key, the key will be created in the default location ~/.config/proxmox-backup/encryption-key.json. The proxmox-backup-client will also search this location by default to get the key, in case the --keyfile parameter is not specified.
You can also avoid entering the passwords by setting the environment variables PBS_PASSWORD and PBS_ENCRYPTION_PASSWORD.
In the above command, I didn't mention the --repository parameter, because I already have added an environment variable. If you didn't add the environment variable, you must specify the --repository along with the datastore as shown below.
# proxmox-backup-client backup root.pxar:/etc --repository 192.168.1.200:backups --keyfile /root/my-backup.key
List Backup Groups and Snapshots
First, let us list all the available snapshots in the PBS using command:
# proxmox-backup-client snapshot list
You will see all available snapshots in the Proxmox Backup Server.
+======================================+===========+========================================================+ | snapshot | size | files | +======================================+===========+========================================================+ | ct/102/2023-02-14T12:37:39Z | 2.462 GiB | catalog.pcat1 client.log index.json pct.conf root.pxar | +--------------------------------------+-----------+--------------------------------------------------------+ | host/Debian11CT/2023-02-21T10:10:07Z | 2.542 GiB | catalog.pcat1 index.json root.pxar | +--------------------------------------+-----------+--------------------------------------------------------+ | host/Debian11CT/2023-02-21T12:15:33Z | 2.552 GiB | catalog.pcat1 index.json root.pxar | +--------------------------------------+-----------+--------------------------------------------------------+ | host/Debian11CT/2023-02-22T10:47:12Z | 1.634 MiB | catalog.pcat1 etc.pxar index.json | +--------------------------------------+-----------+--------------------------------------------------------+ | vm/106/2023-02-13T11:04:28Z | 50 GiB | client.log drive-scsi0.img index.json qemu-server.conf | +======================================+===========+========================================================+
As you see in the above output, I have one Container backup snapshot, one VM backup snapshot and 3 host system snapshots.
If you want to list only the backup groups (not snapshots), simply run:
# proxmox-backup-client list +=================+======================================+==============+========================================================+ | group | last snapshot | backup-count | files | +=================+======================================+==============+========================================================+ | ct/102 | ct/102/2023-02-14T12:37:39Z | 1 | catalog.pcat1 client.log index.json pct.conf root.pxar | +-----------------+--------------------------------------+--------------+--------------------------------------------------------+ | host/Debian11CT | host/Debian11CT/2023-02-22T10:47:12Z | 3 | catalog.pcat1 etc.pxar index.json | +-----------------+--------------------------------------+--------------+--------------------------------------------------------+ | vm/106 | vm/106/2023-02-13T11:04:28Z | 1 | client.log drive-scsi0.img index.json qemu-server.conf | +=================+======================================+==============+========================================================+
As you can see in the above output, all the backup groups and the most recent (i.e. last) snapshot in each backup group are displayed.
To list the individual snapshots in a backup group, for example host/Debian11CT, run:
# proxmox-backup-client snapshot list host/Debian11CT +======================================+===========+====================================+ | snapshot | size | files | +======================================+===========+====================================+ | host/Debian11CT/2023-02-21T10:10:07Z | 2.542 GiB | catalog.pcat1 index.json root.pxar | +--------------------------------------+-----------+------------------------------------+ | host/Debian11CT/2023-02-21T12:15:33Z | 2.552 GiB | catalog.pcat1 index.json root.pxar | +--------------------------------------+-----------+------------------------------------+ | host/Debian11CT/2023-02-22T10:47:12Z | 1.634 MiB | catalog.pcat1 etc.pxar index.json | +======================================+===========+====================================+
This is how we list the backup groups, individual snapshots in a backup group and all snapshots from all backup groups.
Restore Data using Proxmox Backup Client
What is the point of backup if we can not restore them? Fortunately, Proxmox Backup Client makes the restoration task easier.
First, find the snapshot that you want to restore. To do so, list all snapshots in a backup group using command:
# proxmox-backup-client snapshot list Password for "root@pam": ******* +======================================+===========+========================================================+ | snapshot | size | files | +======================================+===========+========================================================+ | ct/102/2023-02-14T12:37:39Z | 2.462 GiB | catalog.pcat1 client.log index.json pct.conf root.pxar | +--------------------------------------+-----------+--------------------------------------------------------+ | host/Debian11CT/2023-02-21T10:10:07Z | 2.542 GiB | catalog.pcat1 index.json root.pxar | +--------------------------------------+-----------+--------------------------------------------------------+ | host/Debian11CT/2023-02-21T12:15:33Z | 2.552 GiB | catalog.pcat1 index.json root.pxar | +--------------------------------------+-----------+--------------------------------------------------------+ | host/Debian11CT/2023-02-22T10:47:12Z | 1.634 MiB | catalog.pcat1 etc.pxar index.json | +--------------------------------------+-----------+--------------------------------------------------------+ | vm/106/2023-02-13T11:04:28Z | 50 GiB | client.log drive-scsi0.img index.json qemu-server.conf | +======================================+===========+========================================================+
I am going to restore the snapshot named "ct/102/2023-02-14T12:37:39Z", so I run the following command to restore the snapshot backup:
# proxmox-backup-client restore ct/102/2023-02-14T12:37:39Z root.pxar /target/path/
Replace the "/target/path" with the location where yo want to restore the backup.
To get the contents of any archive, you can restore the index.json file in the repository to the target path '-'. This will dump the contents to the standard output.
# proxmox-backup-client restore ct/102/2023-02-14T12:37:39Z index.json -
Sample output:
{
"backup-id": "102",
"backup-time": 1676378259,
"backup-type": "ct",
"files": [
{
"crypt-mode": "none",
"csum": "99ef8ed6064c9464061f50798fef97096931f29edb9eef99b7bc939c796503a9",
"filename": "pct.conf.blob",
"size": 252
},
{
"crypt-mode": "none",
"csum": "388829b6b9b7264afca7b86dfd33535dda88d9eed739f4ff9f3646ffed15d858",
"filename": "root.pxar.didx",
"size": 2642140467
},
{
"crypt-mode": "none",
"csum": "caf1bae0f25c449b4883375da96484fc3acb59fc7cfc34f083f1407b042aa204",
"filename": "catalog.pcat1.didx",
"size": 1109866
}
],
"signature": null,
"unprotected": {
"chunk_upload_stats": {
"compressed_size": 1076670895,
"count": 724,
"duplicates": 0,
"size": 2636955824
},
"notes": "Debian11CT"
}
}Restore Individual Files from a Snapshot
if you want to restore only certain files, you can use the interactive recovery shell using command:
# proxmox-backup-client catalog shell ct/102/2023-02-14T12:37:39Z root.pxar
The above command will put you into an interactive shell.
Starting interactive shell pxar:/ >
You can use the "ls" command to view the contents of the snapshot. I am going to list the contents of the home directory:
pxar:/ > ls home/ostechnix/ .bash_history .bash_logout .bashrc .cache .dotnet .gnupg .local .profile .ssh .wget-hsts File1.txt File2.txt dotnet-install.sh go1.19.5.linux-amd64.tar.gz go_projects myfile.txt ramfetch test pxar:/ >
You can use the restore command to restore all the files in the snapshot. However it is a good practice to use restore command with the --pattern <glob> option to restore all specific type of files. For example, the following command will scan through all the directories below /home and restore all files ending in .txt.
pxar:/ > restore target/ --pattern home/ostechnix/**/*.txt
Do not forget to replace the target path with your own.
Type exit and press ENTER to exit interactive shell.
Mount Backup Archives via FUSE
Using Proxmox backup Client, we can mount a snapshot as read-only filesystem in your client system and look into the contents of that particular snapshot from the client system itself.
First, let us create a mount point for the snapshot:
# mkdir /mnt/mybackup
Then, list the available snapshots in a backup group using command:
# proxmox-backup-client snapshot list
Now mount any one of the available snapshot using command:
# proxmox-backup-client mount host/Debian11CT/2023-02-21T10:10:07Z root.pxar /mnt/mybackup/
If you want to mount an encrypted backup, make sure you have specified the encryption key:
# proxmox-backup-client mount host/Debian11CT/2023-02-21T10:10:07Z root.pxar /mnt/mybackup/ --keyfile /root/my-backup.key
You can now view the contents in the snapshot using ls command:
# ls /mnt/mybackup bin dev home lib32 libx32 media opt root sbin sys usr boot etc lib lib64 lost+found mnt proc run srv tmp var
Prune and Remove Backups
The prune command is used to remove individual snapshots or a whole backup group.
To manually remove a backup snapshot, run:
# proxmox-backup-client snapshot forget host/Debian11CT/2023-02-21T10:10:07Z
If you want to forget a snapshot that is contained in the root namespace, add --ns parameter:
# proxmox-backup-client snapshot forget host/Debian11CT/2023-02-21T10:10:07Z --ns <ns>
You can also specify how many backups you want to keep while pruning. For example, I am going to keep one backup and 3 weekly backups. So the command would be:
# proxmox-backup-client prune host/Debian11CT --keep-daily 1 --keep-weekly 3
It is always recommended to use --dry-run parameter to know what is going to happen without actually deleting anything. This will simply run a simulation but will not delete anything.
# proxmox-backup-client prune host/Debian11CT --dry-run --keep-daily 1 --keep-weekly 3
Sample Output:
+======================================+==========================+========+ | snapshot | date | action | +======================================+==========================+========+ | host/Debian11CT/2023-02-21T10:10:07Z | Tue Feb 21 10:10:07 2023 | remove | +--------------------------------------+--------------------------+--------+ | host/Debian11CT/2023-02-21T12:15:33Z | Tue Feb 21 12:15:33 2023 | remove | +--------------------------------------+--------------------------+--------+ | host/Debian11CT/2023-02-22T10:47:12Z | Wed Feb 22 10:47:12 2023 | keep | +======================================+==========================+========+
By including --dry-run option, you can see what is going to happen if we run prune command.
After making sure which backups are going to be deleted, you can run the actual prune command without --dry-run option.
Garbage Collection
Please note that the prune command will remove only the backup index files. It won't touch the data from the datastore.
To remove the left-over data in the datastore, run the garbage collection using command:
# proxmox-backup-client garbage-collect
Sample Output:
starting garbage collection on store backups Start GC phase1 (mark used chunks) marked 20% (1 of 5 index files) marked 40% (2 of 5 index files) marked 60% (3 of 5 index files) marked 80% (4 of 5 index files) marked 100% (5 of 5 index files) Start GC phase2 (sweep unused chunks) processed 1% (35 chunks) processed 2% (62 chunks) processed 3% (88 chunks) processed 4% (121 chunks) processed 5% (154 chunks) [...] processed 95% (2496 chunks) processed 96% (2527 chunks) processed 97% (2554 chunks) processed 98% (2581 chunks) processed 99% (2606 chunks) Removed garbage: 181.901 MiB Removed chunks: 107 Original data usage: 52.463 GiB On-Disk usage: 6.558 GiB (12.50%) On-Disk chunks: 2531 Deduplication factor: 8.00 Average chunk size: 2.653 MiB TASK OK
It is recommended to run the garbage-collect command on regular basis to remove unwanted files and free up the disk space.
Conclusion
Proxmox Backup Client is useful when you want to create file level backup and restore. For some reason, you may want to exclude some files/folders from backup when backing up a Proxmox VM or Container. In that case, you can use Proxmox Backup Client.
Not just Proxmox VMs or Containers, Proxmox Backup Client program comes handy when you want to backup files from physical machines as well.
As you can see, working with Proxmox backup Client to backup and restore files is quite easy! It is also completely free to use! So if you're looking for an enterprise grade backup application for your homelab, Proxmox Backup Client is highly recommended!
