ThisCalculator

Everyday

Automate Proxmox Backups with Home Assistant

Updated · Standard formula, shown below

Automate Proxmox Backups with Home Assistant

This guide shows you how to automate backups for Proxmox VMs and LXC containers using Home Assistant. You’ll set up a Home Assistant automation that triggers backups on your Proxmox server at scheduled times, with optional retention and notifications. You’ll need a Proxmox server with the API enabled, and Home Assistant with SSH access to that server.

What You’ll Need

  • A Proxmox VE server (version 6 or newer) with the API enabled (default port 8006).
  • Home Assistant (HA) with SSH integration or a shell command that can reach the Proxmox server.
  • SSH key-based authentication from Home Assistant to Proxmox (password auth works but is less secure).
  • Basic familiarity with YAML in Home Assistant.

Step-by-Step

  1. Enable the Proxmox API. On Proxmox, go to Datacenter > Permissions > API Tokens. Create a token with the PVEBackup role (or a custom role with VM.Backup and VM.Audit permissions). Note the token ID and secret.
  2. Test the API from Home Assistant. In HA, use the shell_command integration to run a curl command that lists VMs. For example: curl -k -H "Authorization: PVEAPIToken=user@realm!tokenid=secret" https://proxmox-ip:8006/api2/json/cluster/resources. If this works, you can use the API directly. If not, you can fall back to SSH.
  3. Set up SSH key authentication (recommended). Generate an SSH key on Home Assistant (if not already present) and copy the public key to Proxmox’s /root/.ssh/authorized_keys. Test with ssh root@proxmox-ip.
  4. Create a backup script on Proxmox. Write a shell script (e.g., /root/backup_vms.sh) that uses vzdump to back up specific VMs and containers. Example: vzdump 100 101 --mode snapshot --storage local --compress zstd --mailto admin@example.com. Make it executable.
  5. Test the script manually. Run the script from the Proxmox shell and verify backups appear in the storage. Adjust the VM IDs and storage as needed.
  6. Add a shell_command in Home Assistant. In configuration.yaml, add: 
    shell_command:
  proxmox_backup: "ssh root@proxmox-ip /root/backup_vms.sh"

    If you prefer API, use curl instead.

  7. Create an automation. In Home Assistant, go to Settings > Automations > Create New. Choose a trigger (e.g., Time, at 2:00 AM). Add an action: service: shell_command.proxmox_backup. Save.
  8. Add notifications (optional). Add a second action to send a notification via notify service when the backup completes. Use a delay or check the exit code via a script.
  9. Test the automation. Run the automation manually from the HA UI. Check Proxmox logs and storage to confirm backups are created.
  10. Set retention (optional). In the script, use --prune-backups keep-daily=7 to keep only 7 daily backups. Adjust as needed.

Common Mistakes

  • Using the wrong VM IDs. Verify the IDs with qm list for VMs and pct list for containers.
  • Insufficient permissions. The API token must have backup permissions; otherwise, the API call fails silently.
  • SSH host key not accepted. When using SSH, the first connection prompts for host key verification. Use ssh-keyscan to pre-add the key to HA’s known_hosts.
  • Backup storage full. Check available space on the backup storage. Use df -h on Proxmox.
  • Automation runs but script fails. The automation may not capture the exit code. Use a script that logs to a file for debugging.

Tips

  • Use --mode snapshot for running VMs to avoid downtime.
  • Store backups on a separate storage or NFS share to protect against disk failure.
  • Schedule backups at off-peak hours to avoid performance impact.
  • Use compression (e.g., --compress zstd) to save space.
  • Test restoring a backup periodically to ensure it works.
  • Consider using the Proxmox backup server (PBS) for more advanced deduplication.

Troubleshooting

If the automation runs but no backup appears, check the following:

  • Check the script output. Run the script manually on Proxmox and look for errors like “no such VMâ€� or “storage not foundâ€�.
  • Check HA logs. In Home Assistant, go to Settings > System > Logs. Look for errors from shell_command.
  • Test the shell command directly. In HA, go to Developer Tools > Services and call shell_command.proxmox_backup. If it fails, the output will show in the log.
  • SSH connection refused. Ensure SSH is running on Proxmox (systemctl status ssh) and the port is open.
  • API token invalid. Verify the token ID and secret are correct, and that the token has not expired.
  • Storage path incorrect. In the script, specify the storage ID exactly as it appears in Proxmox (e.g., local or nfs-backup).

Frequently Asked Questions

Can I back up all VMs and containers at once?

Yes, use vzdump --all to back up all VMs and containers. However, this may take longer and is not recommended for large environments.

How do I exclude a VM from the backup?

List specific VM IDs in the script, or use --exclude with --all. For example: vzdump --all --exclude 100,101.

Can I use the Proxmox API instead of SSH?

Yes, the API is more secure and allows for granular control. Use curl commands in the shell_command, but ensure the token has the correct permissions.

How do I keep only the last N backups?

Use the --prune-backups option in vzdump. For example, --prune-backups keep-last=5 keeps only the last 5 backups.

What if my Proxmox server is behind NAT?

Ensure Home Assistant can reach the Proxmox IP. If not, set up a VPN or port forwarding. Alternatively, use a local network connection.

Can I get a notification when the backup fails?

Yes, modify the script to send an email or use Home Assistant’s notification services. In the script, check the exit code and send a notification accordingly.

Related

Method: the standard formula for this calculation, rounded as each result states. See how the calculators work or report an error.