Proxmox VE

Proxmox VE is an open-source server virtualization environment. This integration allows you to poll various data from your instance.

After configuring this component, the binary sensors automatically appear.

Configuration

You should have at least one VM or container entry configured, else this integration won't do anything.

To use the proxmoxve component, add the following configuration to your configuration.yaml file:

# Example configuration.yaml entry
proxmoxve:
  - host: IP_ADDRESS
    username: USERNAME
    password: PASSWORD
    nodes:
      - node: NODE_NAME
        vms:
          - VM_ID
        containers:
          - CONTAINER_ID

Configuration Variables

host

(string)(Required)

IP address of the Proxmox VE instance.

port

(integer)(Optional)

The port number on which Proxmox VE is running.

Default value:

8006

verify_ssl

(boolean)(Optional)

Whether to do strict validation on SSL certificates. If you use a self signed SSL certificate you need to set this to false.

Default value:

true

username

(string)(Required)

The username used to authenticate.

password

(string)(Required)

The password used to authenticate.

realm

(string)(Optional)

The authentication realm of the user.

Default value:

pam

nodes

(map)(Required)

List of the Proxmox VE nodes to monitor.

node

(string)(Required)

Name of the node

vms

(list)(Optional)

List of the QEMU VMs to monitor.

containers

(list)(Optional)

List of the LXC containers to monitor.

Example with multiple VMs and no containers:

proxmoxve:
  - host: IP_ADDRESS
    username: USERNAME
    password: PASSWORD
    nodes:
      - node: NODE_NAME
        vms:
          - VM_ID_1
          - VM_ID_2

Binary Sensor

The integration will automatically create a binary sensor for each tracked virtual machine or container. The binary sensor will either be on if the VM’s state is running or off if the VM’s state is different.

The created sensor will be called binary_sensor.NODE_NAME_VMNAME_running.

Proxmox Permissions

To be able to retrieve the status of VMs and containers, the user used to connect must minimally have the VM.Audit privilege. Below is a guide to how to configure a new user with the minimum required permissions.

Create Home Assistant Role

Before creating the user, we need to create a permissions role for the user.

Click Datacenter
Open Permissions and click Roles
Click the Create button above all the existing roles
name the new role (e.g., “home-assistant”)
Click the arrow next to privileges and select VM.Audit in the dropdown
Click Create

Create Home Assistant User

Creating a dedicated user for Home Assistant, limited to only the role just created is the most secure method. These instructions use the pve realm for the user. This allows a connection, but ensures that the user is not authenticated for SSH connections. If you use the pve realm, just be sure to add realm: pve to your configuration.

Click Datacenter
Open Permissions and click Users
Click Add
Enter a username (e.g., “hass”)
Set the realm to “Proxmox VE authentication server”
Enter a secure password (it can be complex as you will only need to copy/paste it into your Home Assistant configuration)
Ensure Enabled is checked and Expire is set to “never”
Click Add

Add User Permissions to Assets

To apply the user and role just created, we need to give it permissions

Click Datacenter
Click Permissions
Open Add and click User Permission
Select “/” for the path
Select your Home Assistant user (hass)
Select the Home Assistant role (home-assistant)
Make sure Propigate is checked