> For the complete documentation index, see [llms.txt](https://docs.eazybackup.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.eazybackup.com/guides/proxmox-ve-backup.md). # Proxmox VE Backup ## Proxmox VE Backup ### How to Configure Proxmox VE Backup The Proxmox VE Protected Item backs up Proxmox virtual machines and Linux containers by connecting directly to a standalone Proxmox VE server or a Proxmox VE cluster. For each virtual machine selected for backup, eazyBackup creates a temporary snapshot of the VM and streams the required data directly into the eazyBackup Chunking engine. Changed Block Tracking can optionally be used to reduce the amount of data that must be read during subsequent backups. After the data has been captured, eazyBackup removes the temporary snapshot from the Proxmox host. The machine running the eazyBackup client does not require temporary disk space equal to the size of the virtual machines being protected. ### Performance Virtual machine disk data is streamed from Proxmox VE to the machine running the eazyBackup client. This can generate a significant amount of traffic on the internal network. For the best performance, install eazyBackup in a virtual machine on the same local network as the Proxmox environment. When practical, run the eazyBackup VM on the same Proxmox cluster being protected. The eazyBackup client process is named: ``` backup-tool ``` The machine running `backup-tool` must be able to establish SSH connections to the Proxmox server and, for a cluster, every node in the cluster. You can configure how many virtual machines eazyBackup backs up concurrently. Backing up multiple VMs at the same time may improve overall throughput, but it also increases storage, network, CPU and memory utilization. Changed Block Tracking can read only disk blocks that have changed since the previous successful backup. Unallocated disk areas are also skipped during both full and Changed Block Tracking backups. ### Requirements #### eazyBackup client * A current version of the eazyBackup desktop client. * The `backup-tool` process must be running. * The client must be on the same network as the Proxmox environment. * The client must be able to reach TCP port 22 on the Proxmox server and every node being protected. * For a cluster, the node names and addresses returned by Proxmox must be reachable and resolvable from the machine running eazyBackup. #### Proxmox VE * Proxmox VE 8.x or 9.x. * SSH access enabled on every Proxmox node. * Root access during the initial account configuration. * A root account or a dedicated non-root Linux account with passwordless `sudo` access. ### Authentication Overview eazyBackup supports the following Proxmox authentication methods: * Root account with a password. * Root account with a private SSH key. * Dedicated non-root account with a password and passwordless `sudo`. * Dedicated non-root account with a private SSH key and passwordless `sudo`. Using a dedicated non-root account is recommended. A Proxmox VE cluster requires two separate SSH authentication stages. Understanding these stages is important because successfully authenticating to the first node does not necessarily mean that eazyBackup can access all nodes in the cluster. #### Authentication stage 1: Initial Proxmox connection The eazyBackup `backup-tool` process connects to the Proxmox node entered in the Protected Item configuration. This first connection uses the authentication method selected in eazyBackup: * Password; or * Private SSH key. The node entered in the eazyBackup configuration is referred to throughout this guide as the **primary node**. #### Authentication stage 2: Access to discovered nodes After connecting to the primary node, eazyBackup discovers the nodes that belong to the Proxmox environment. For a non-root account, eazyBackup looks for a usable private SSH key in the Proxmox user's home directory on the primary node: ``` ~/.ssh/ ``` For example, if the Proxmox Linux username is `eazybackup`, the directory will normally be: ``` /home/eazybackup/.ssh/ ``` The matching public key must be authorized for the same user on every Proxmox node. The private key entered in the eazyBackup Protected Item is used for the initial connection. It does not replace the requirement to configure the Proxmox user's SSH directory for cluster-node access. > **Important:** Create the SSH key while logged in as the same Linux user that will be entered in the eazyBackup Protected Item. A key created under `/root/.ssh/` will not be found when eazyBackup is configured to use a different user. ### Recommended Non-Root Account Configuration The following instructions create a dedicated Linux account named: ``` eazybackup ``` You may use a different username, but the same username must be used consistently throughout the configuration. Run the account-creation commands as `root`. ### Configure a Single Proxmox VE Server Use this procedure when the Proxmox environment contains only one server and is not part of a multi-node cluster. Even on a single-server installation, configure an SSH key in the non-root user's home directory. The eazyBackup client may check this directory while discovering the Proxmox environment. #### Step 1: Install sudo Proxmox VE may not have the `sudo` package installed by default. Log in to the Proxmox server as `root` and run: ```bash apt update apt install -y sudo ``` Confirm that `sudo` and `visudo` are available: ```bash sudo --version visudo --version ``` #### Step 2: Create the dedicated user Run: ```bash useradd -m -s /bin/bash eazybackup passwd eazybackup ``` The `passwd` command will prompt you to create a password for the account. If the user already exists, do not run `useradd` again. Confirm its home directory with: ```bash getent passwd eazybackup ``` The output should show a valid home directory, normally: ``` /home/eazybackup ``` #### Step 3: Add the user to the sudo group Run: ```bash usermod -aG sudo eazybackup ``` Confirm the group membership: ```bash id eazybackup ``` The output should include the `sudo` group. #### Step 4: Configure passwordless sudo Open a dedicated sudoers configuration file: ```bash visudo -f /etc/sudoers.d/eazybackup ``` Add the following line: ``` eazybackup ALL=(ALL:ALL) NOPASSWD: ALL ``` Save and close the file. Set the required permissions: ```bash chmod 440 /etc/sudoers.d/eazybackup ``` Validate the configuration: ```bash visudo -cf /etc/sudoers.d/eazybackup ``` The validation command should report that the file parsed successfully. #### Step 5: Generate the SSH key as the dedicated user Switch to the new account using a login shell: ```bash su - eazybackup ``` Confirm the username and home directory: ```bash whoami echo "$HOME" ``` Expected output: ``` eazybackup /home/eazybackup ``` Create the SSH directory: ```bash mkdir -p ~/.ssh chmod 700 ~/.ssh ``` Generate an RSA private key without a passphrase: ```bash ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N "" ``` Authorize the matching public key on the server: ```bash cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys ``` Set the required permissions: ```bash chmod 600 ~/.ssh/id_rsa chmod 644 ~/.ssh/id_rsa.pub chmod 600 ~/.ssh/authorized_keys ``` The directory should now contain: ``` ~/.ssh/id_rsa ~/.ssh/id_rsa.pub ~/.ssh/authorized_keys ``` * `id_rsa` is the private key. * `id_rsa.pub` is the public key. * `authorized_keys` contains the public keys permitted to log in as this user. #### Step 6: Test SSH and sudo While still logged in as `eazybackup`, connect to the server using its management IP address or DNS name: ```bash ssh \ -i ~/.ssh/id_rsa \ -o IdentitiesOnly=yes \ -o StrictHostKeyChecking=accept-new \ eazybackup@ \ 'sudo -n true && hostname && echo "SSH and sudo are working"' ``` Replace `` with the IP address or DNS name that will be entered in eazyBackup. For example: ```bash ssh \ -i ~/.ssh/id_rsa \ -o IdentitiesOnly=yes \ -o StrictHostKeyChecking=accept-new \ eazybackup@192.168.1.50 \ 'sudo -n true && hostname && echo "SSH and sudo are working"' ``` The command must complete without requesting a password and should display: ``` SSH and sudo are working ``` Do not continue to the eazyBackup configuration until this test succeeds. ### Configure a Proxmox VE Cluster Use this procedure for a Proxmox environment containing multiple nodes. The dedicated Linux user must exist on every node. The primary node must contain the private SSH key, and the matching public key must be authorized for that user on every cluster node. #### Step 1: Select the primary node Choose one online Proxmox node to use as the primary node. This is the node whose address you will enter in the eazyBackup Protected Item. The private key used for cluster-node access must be generated in the dedicated user's home directory on this node. #### Step 2: Install sudo on every node Log in as `root` on every Proxmox node and run: ```bash apt update apt install -y sudo ``` #### Step 3: Create the same user on every node On every node, run: ```bash useradd -m -s /bin/bash eazybackup passwd eazybackup usermod -aG sudo eazybackup ``` Use the same username on every node. Using the same password on every node can simplify the initial `ssh-copy-id` configuration, although key-based authentication will be used after setup is complete. If the account already exists on a node, confirm its home directory: ```bash getent passwd eazybackup ``` #### Step 4: Configure passwordless sudo on every node On every node, run: ```bash visudo -f /etc/sudoers.d/eazybackup ``` Add: ``` eazybackup ALL=(ALL:ALL) NOPASSWD: ALL ``` Save the file and run: ```bash chmod 440 /etc/sudoers.d/eazybackup visudo -cf /etc/sudoers.d/eazybackup ``` Repeat this process on every node. #### Step 5: Generate the SSH key on the primary node On the primary node, switch to the dedicated user: ```bash su - eazybackup ``` Confirm the account: ```bash whoami echo "$HOME" ``` Create the SSH directory: ```bash mkdir -p ~/.ssh chmod 700 ~/.ssh ``` Generate the key: ```bash ssh-keygen -t rsa -b 4096 -f ~/.ssh/id_rsa -N "" ``` Authorize the key on the primary node itself: ```bash cat ~/.ssh/id_rsa.pub >> ~/.ssh/authorized_keys ``` Set the required permissions: ```bash chmod 600 ~/.ssh/id_rsa chmod 644 ~/.ssh/id_rsa.pub chmod 600 ~/.ssh/authorized_keys ``` #### Step 6: Copy the public key to every other node While logged in as `eazybackup` on the primary node, run `ssh-copy-id` for every other node: ```bash ssh-copy-id -i ~/.ssh/id_rsa.pub eazybackup@ ssh-copy-id -i ~/.ssh/id_rsa.pub eazybackup@ ``` Continue until the key has been copied to every node. For example: ```bash ssh-copy-id -i ~/.ssh/id_rsa.pub eazybackup@192.168.1.52 ssh-copy-id -i ~/.ssh/id_rsa.pub eazybackup@192.168.1.53 ``` You may be prompted for each node's `eazybackup` account password during this step. Only the public key is copied to the other nodes. Do not copy `id_rsa` using `ssh-copy-id`. #### Step 7: Test every node From the primary node, test the primary node itself: ```bash ssh \ -i ~/.ssh/id_rsa \ -o IdentitiesOnly=yes \ -o StrictHostKeyChecking=accept-new \ eazybackup@ \ 'sudo -n true && hostname' ``` Then test every additional cluster node: ```bash ssh \ -i ~/.ssh/id_rsa \ -o IdentitiesOnly=yes \ -o StrictHostKeyChecking=accept-new \ eazybackup@ \ 'sudo -n true && hostname' ``` ```bash ssh \ -i ~/.ssh/id_rsa \ -o IdentitiesOnly=yes \ -o StrictHostKeyChecking=accept-new \ eazybackup@ \ 'sudo -n true && hostname' ``` Each command must: * Connect without requesting a password. * Display the correct node hostname. * Complete without a sudo password prompt. * Complete without a permission error. Do not continue until the test succeeds against every node. #### Step 8: Verify cluster node addresses On the primary node, list the cluster members: ```bash sudo pvecm nodes ``` Verify that every listed node is online. Confirm that the machine running the eazyBackup `backup-tool` process can resolve and reach each node using the addresses returned by the Proxmox environment. Test TCP port 22 from the eazyBackup machine where possible: ```bash nc -vz 22 ``` If `nc` is not installed, an SSH connection can be used instead: ```bash ssh eazybackup@ ``` Firewall rules must permit the eazyBackup machine to reach TCP port 22 on every node. ### Configure Authentication in eazyBackup After completing the single-server or cluster configuration, open the eazyBackup desktop application and create or edit the Proxmox Protected Item. You may authenticate using a password or private key. #### Option 1: Password authentication Enter: * **Server address:** The management IP address or DNS name of the primary Proxmox node. * **Username:** `eazybackup` * **Authentication method:** Password * **Password:** The Linux password assigned to the `eazybackup` account. The password authenticates the initial connection from `backup-tool` to the primary node. The SSH key stored in: ``` /home/eazybackup/.ssh/id_rsa ``` is still required for the second authentication stage. This means that selecting Password authentication in eazyBackup does not eliminate the need to create the server-side SSH key. #### Option 2: Private-key authentication To use private-key authentication, display the private key on the primary node: ```bash cat /home/eazybackup/.ssh/id_rsa ``` Copy the entire output, including the opening and closing lines: ``` -----BEGIN OPENSSH PRIVATE KEY----- ... -----END OPENSSH PRIVATE KEY----- ``` Paste the complete private key into the Private Key field in eazyBackup. Do not paste the contents of: ``` /home/eazybackup/.ssh/id_rsa.pub ``` The `.pub` file is a public key and cannot be used in a field that expects a private key. The matching public key must remain in the following file on every applicable node: ``` /home/eazybackup/.ssh/authorized_keys ``` Treat the private key as a sensitive credential. Do not include it in support tickets, screenshots, email messages or documentation. ### Root Authentication eazyBackup can also connect using the Proxmox `root` account. Root authentication may be simpler because Proxmox clusters normally maintain SSH access for administrative cluster operations. However, using a dedicated non-root account with passwordless `sudo` provides clearer separation between backup access and general administrative access. When using root authentication: * Enter `root` as the username. * Select Password or Private Key authentication. * Make sure SSH permits the selected root authentication method. * Confirm that root can access every required cluster node. * Do not use a Proxmox API token in the SSH username or password fields. ### Configure the Proxmox Protected Item #### Protected Item Configuration in the eazyBackup Desktop App 1. Open the eazyBackup desktop application. 2. Add a new Protected Item. 3. Select **Proxmox** from the Protected Item list. 4. Enter the Proxmox server or cluster credentials. For a cluster, enter the address of the primary node on which the dedicated user's private SSH key was generated. 5. Select **Test Connection**. A successful test confirms that eazyBackup can authenticate to the primary node and discover the Proxmox environment. For a cluster, the test must also be able to authenticate to the remaining nodes. 6. Use the resource picker to select the virtual machines, containers and disks to protect. eazyBackup can protect: * All supported virtual machines and containers in a cluster. * All supported workloads on an individual node. * Individual virtual machines or containers. * Individual virtual machine disks. 7. Select the isolation method for supported Linux containers. 8. Select the backup type: * **Changed Block Tracking:** Reads disk blocks that have changed since the previous successful backup. * **Full backup:** Reads all allocated data from the selected disks. Changed Block Tracking is the recommended default for supported environments. 9. Save the Protected Item. 10. Configure a Storage Vault and backup schedule. 11. Run an initial backup and review the job log. ### Container Isolation Isolation mode determines how a Linux container is handled while its backup is being created. These options currently apply only to containers. #### Default — Snapshot eazyBackup creates a temporary snapshot of the container. The container continues running during the backup. This is normally the fastest and least disruptive option, but the container must reside on storage that supports snapshots. #### Stop eazyBackup stops the container before backing it up and restarts it after the backup job completes. This option is disruptive, but it can be used when the container resides on storage that does not support snapshots. #### Suspend eazyBackup suspends the container before backing it up and resumes it after the backup job completes. This option is disruptive, but it can be used when snapshot-based isolation is unavailable. ### Authentication Troubleshooting #### No SSH private keys found in `~/.ssh/` Example error: ``` failed to get connection to other nodes in the cluster: No SSH private keys found in ~/.ssh/ ``` This normally means the initial connection to the primary Proxmox node succeeded, but eazyBackup could not find a private key for the second SSH authentication stage. Check the account's home directory: ```bash getent passwd eazybackup ``` Check the SSH directory as that user: ```bash su - eazybackup ls -la ~/.ssh ``` Verify that the following file exists: ``` ~/.ssh/id_rsa ``` A common cause is generating the key while logged in as `root`. This creates: ``` /root/.ssh/id_rsa ``` That key will not be found when the Protected Item is configured with the username `eazybackup`. Generate the key again while logged in as the configured user. #### SSH handshake failed: unable to authenticate using public key Example error: ``` ssh: handshake failed: ssh: unable to authenticate, attempted methods [none publickey], no supported methods remain ``` This means eazyBackup was able to read and parse the private key, but the Proxmox SSH server did not accept it. Check the following: * The correct Linux username was entered in eazyBackup. * The private key belongs to that username. * The matching public key appears in the user's `authorized_keys` file. * The public and private keys are a matching pair. * The SSH directory and files have the correct permissions. * The account is not locked or disabled. * The SSH server permits public-key authentication. Compare the key fingerprints: ```bash ssh-keygen -lf /home/eazybackup/.ssh/id_rsa ssh-keygen -lf /home/eazybackup/.ssh/id_rsa.pub ``` The fingerprints should match. #### Parsing SSH private key: no key found Example error: ``` Parsing SSH private key: ssh: no key found ``` This usually means a public key was pasted into the Private Key field. A public key normally appears as a single line beginning with: ``` ssh-rsa ``` A valid OpenSSH private key begins with: ``` -----BEGIN OPENSSH PRIVATE KEY----- ``` Display the correct private key with: ```bash cat /home/eazybackup/.ssh/id_rsa ``` Never send the private key to eazyBackup support. #### `visudo`: command not found Install the `sudo` package: ```bash apt update apt install -y sudo ``` Then try: ```bash visudo -f /etc/sudoers.d/eazybackup ``` #### Sudo requests a password Test passwordless sudo: ```bash su - eazybackup sudo -n true ``` If the command produces an error, validate the sudoers file: ```bash su - visudo -cf /etc/sudoers.d/eazybackup ``` The file must contain: ``` eazybackup ALL=(ALL:ALL) NOPASSWD: ALL ``` #### One or more cluster nodes cannot be reached Confirm that all nodes are online: ```bash pvecm nodes ``` From the machine running eazyBackup, verify that each node can be reached over TCP port 22. Also verify that cluster node names resolve to the correct management addresses. A cluster may return hostnames rather than the IP address originally entered in eazyBackup. Those hostnames must be resolvable from the eazyBackup machine. #### Test Connection succeeds but the backup fails A successful Test Connection does not guarantee that every selected VM disk and storage backend can be accessed during a backup. Review the backup job log and confirm: * Every node is reachable. * The configured user has passwordless sudo. * The selected VM is located on an online node. * The underlying Proxmox storage is available. * Snapshot creation is supported and succeeds. * The eazyBackup machine has sufficient network connectivity. * No firewall or intrusion-prevention system is terminating long-running SSH sessions. ### Restore A Proxmox Protected Item can be restored using several methods: * Direct restore to Proxmox. * Direct restore to Microsoft Hyper-V. * Direct restore to VMware. * Granular restore of individual files and folders from a guest. * Restore of disk image files in `*.img` format. ### Restore Directly to Proxmox 1. Open the Restore section in eazyBackup. 2. Select the Storage Vault and Protected Item containing the required backup. 3. Select **Restore to Proxmox**. 4. Select the virtual machines to restore. 5. Enter the credentials for the destination Proxmox server or cluster. The destination may be the original Proxmox environment or a different compatible Proxmox environment. 6. Browse the destination nodes and storage, and select where the VM will be restored. 7. Review the restore configuration. 8. Select **Restore** to begin restoring the selected virtual machines.