PBS Documentation

Overview

PBS monitoring extends Proxmox Extended Sensors beyond the virtualization hosts and brings Proxmox Backup Server information into Home Assistant.

A PBS connection focuses on the backup environment: server health, datastore capacity, stored backups, deduplication, maintenance operations and task information.

It can be used alongside PVE monitoring or independently when Home Assistant only needs visibility into a Proxmox Backup Server.

What PBS monitoring covers

A configured PBS connection can provide information from several areas:

• Server health — availability and supported CPU and memory information from the PBS server.
• Datastores — capacity, used and free space, usage and deduplication information.
• Backups — information about the backups stored in each datastore, including summary and latest-backup information.
• Maintenance — status and supported actions for operations such as Garbage Collection, Prune and Verify.
• Tasks — information about PBS operations and their results.
• Sync — supported execution of configured Sync Jobs when they are available.

The exact information available depends on the PBS server, API permissions and what the server or service provider exposes to the configured account.

PBS and PVE provide different information

PVE and PBS represent different parts of the backup process.

PVE can know about the backup jobs and tasks that it executes.

PBS primarily provides information about the backup server, its datastores, stored backup data and PBS-side maintenance operations.

This distinction is important when interpreting backup information.

For example, a backup job can fail while sending data from PVE without creating a completed backup on PBS. The PBS datastore may still report that its existing stored backups are healthy.

Use the information from each system according to what it represents rather than expecting PVE and PBS to report the same view of a backup operation.

Local and hosted PBS environments

PBS monitoring can be used with a locally managed Proxmox Backup Server or with a hosted service that provides compatible API access.

A locally managed server may expose server-level information that a hosted or multi-tenant service does not make available to individual customers.

Restricted server or hardware information on a hosted PBS does not necessarily indicate a problem with Proxmox Extended Sensors.

The integration can only expose information available through the account and API provided by the PBS service.

Multiple PBS servers

Proxmox Extended Sensors V5 treats each configured PBS server as its own Home Assistant connection.

This allows multiple PBS instances to coexist while keeping their server, datastore and maintenance information associated with the correct PBS environment.

This is useful when an installation uses more than one backup destination, such as a local PBS together with an off-site or hosted PBS service.

Home Assistant organization

PBS information is organized into Home Assistant devices and entities representing the server and its datastores.

This keeps datastore-specific information such as usage, backup state and maintenance operations grouped with the resource they belong to.

You do not need to display every PBS entity on a dashboard.

Use the information that helps answer useful operational questions: whether backup storage has enough capacity, whether stored backups are healthy, whether maintenance operations are completing and whether something requires attention.

Where to continue

If this is your first PBS connection, continue with Authentication and Configuration.

The remaining sections explain:

• Datastores
• Backups
• Maintenance
• Tasks
• Troubleshooting

Configuration

Once PBS authentication has been prepared, the server can be added to Proxmox Extended Sensors from Home Assistant.

A PBS connection creates its own Home Assistant configuration entry and remains separate from PVE and Cluster connections.

Add the PBS server

In Home Assistant, open:

Settings → Devices & services → Add Integration

Search for Proxmox Extended Sensors.

Enter the PBS host and select:

Proxmox Backup Server (PBS)

when choosing the server type.

Connect using the PBS API Token

The current V5 PBS setup uses API Token authentication.

Enter the credentials prepared in the Authentication section:

• User
• Token ID
• Token Secret

These are separate values.

The Token ID can be a short name or a complete API token identifier containing !. See Hosted / Remote PBS for the exact rule and a tested hosted example.

Server identity

Each PBS configuration is treated as a distinct server by Proxmox Extended Sensors.

This is particularly important when multiple PBS instances are configured because similarly named resources must remain associated with the correct server.

From a user perspective, each PBS connection should therefore be considered an independent backup environment even when two servers contain datastores with similar purposes or names.

What becomes available

After a successful connection, Proxmox Extended Sensors discovers the PBS information available to the configured account.

Depending on the server and permissions, this can include:

• server health information;
• datastores;
• capacity and deduplication information;
• stored backup information;
• maintenance status;
• PBS tasks;
• supported maintenance actions.

Not every PBS environment exposes every category.

Hosted services in particular may intentionally restrict access to server-level information while still providing datastore and backup information.

Configuration can evolve

As with PVE, the initial configuration does not need to determine how every PBS entity will eventually be used.

Start by confirming that the server and expected datastores are available and that the information relevant to your backup workflow appears correctly.

Dashboard views, notifications and automations can then be added around the information that has a useful purpose.

If the connection succeeds but expected information is missing, see Troubleshooting.

Authentication

Proxmox Extended Sensors V5 uses API Token authentication for PBS connections.

A dedicated account is recommended instead of using a general administrative login.

PBS and PVE use separate authentication systems. A user created in Proxmox VE should not be assumed to exist automatically in Proxmox Backup Server.

Create a dedicated PBS user

Create a dedicated account in Proxmox Backup Server for the Home Assistant integration.

Use the appropriate PBS realm for that account.

Keeping the integration on its own account makes its access easier to identify, manage and revoke without affecting other administrative users.

Assign permissions

The permissions required depend on which PBS features you intend to expose to Home Assistant.

Monitoring datastore and backup information can require less access than executing maintenance operations.

For a full-feature PBS installation, the project documentation has traditionally used the Administrator role at / for the dedicated integration account.

This is a broad role.

Advanced users can choose a more restrictive permission model, but they should verify every feature they intend to use, especially:

• datastore visibility;
• backup information;
• task information;
• Garbage Collection;
• Prune;
• Verify;
• Sync.

A successful authentication does not necessarily prove that the account has permission to use every PBS endpoint required by optional functionality.

Create the API Token

Create an API Token for the dedicated PBS account and save the generated secret securely.

The token secret is a credential.

Do not include it in screenshots, diagnostic logs, issues or other public material.

If a token is recreated, remember that Home Assistant must be updated with the new secret.

Credentials used in Home Assistant

The PBS setup expects:

• User — the complete PBS user including its realm;
• Token ID — the short token name, or the complete API token identifier when required by the provider;
• Token Secret — the generated token secret.

Enter these values separately in the Proxmox Extended Sensors configuration flow.

Once authentication is prepared, continue with Configuration to add the PBS server.

Hosted / Remote PBS

Proxmox Extended Sensors connects through the standard PBS HTTPS API. The PBS server therefore does not need to be on the same local network as Home Assistant, provided its API endpoint is securely reachable.

The integration has been tested successfully with a Proxmox Backup Server hosted by Tuxis, including datastore monitoring and maintenance operations authorized for the account.

Availability depends on the provider

The information and actions available depend on the permissions and API access offered by the provider. Datastore monitoring may work normally while server-level hardware metrics remain unavailable on a hosted or multi-tenant PBS.

Token ID formats

A self-hosted PBS can use a short Token ID:

User:     homeassistant@realm
Token ID: home
Token:    <API token secret>

A hosted provider may require the complete API token identifier. This is the tested Tuxis example:

Host:     https://pbs005.tuxis.nl
User:     FL000XX_USUARIO@pbs
Token ID: FL000XX@pbs!home
Token:    <API token secret>

The integration applies this rule:

• If Token ID already contains !, it is used directly as the complete API token identifier.
• If a short Token ID is provided, the integration constructs the identifier as User!Token ID.

The complete identifier shown above is documented for Tuxis. Do not assume that every hosted PBS provider uses the same account syntax.

Datastores

Datastores are the central storage resources of Proxmox Backup Server.

Proxmox Extended Sensors exposes datastore information to Home Assistant so backup capacity and storage behaviour can be monitored without continuously opening the PBS interface.

Capacity and usage

Datastore monitoring can provide information such as:

• total capacity;
• used space;
• free space;
• usage percentage.

These values provide a quick view of how much backup storage remains available.

Home Assistant can display them on a dashboard or use them as conditions for notifications and automations.

Free space needs context

A datastore does not necessarily need to be almost full before its capacity becomes operationally important.

Backup size, retention policy, maintenance behaviour and expected future growth all affect how much free space is appropriate.

A datastore with significant free capacity can still deserve attention if the next backup cycle is expected to consume a large amount of space.

For this reason, storage trends are often more useful than a single percentage viewed in isolation.

Deduplication

PBS can store duplicate data efficiently by reusing chunks that are already present.

Proxmox Extended Sensors can expose the deduplication information reported for a datastore.

A high deduplication factor can indicate that the stored backups share a significant amount of data, but it should not be interpreted as a health score.

Deduplication describes storage efficiency, not whether the backups themselves are valid.

Datastore information and physical storage are different

The datastore information exposed to Home Assistant represents the PBS storage resource as reported by Proxmox Backup Server.

It does not necessarily describe the physical disks, filesystem, RAID or other storage infrastructure underneath that datastore.

This distinction is especially important with hosted PBS services, where the physical storage layer may not be visible to the customer at all.

Multiple datastores

A PBS server can expose more than one datastore.

Proxmox Extended Sensors keeps datastore-specific information associated with the datastore it belongs to so capacity, backup state and maintenance information can be interpreted independently.

Different datastores can also require different monitoring thresholds depending on their size, retention policy and purpose.

For the complete list of PBS datastore entities, see Reference.

Backups

PBS backup monitoring describes the backup data stored on the Proxmox Backup Server.

This is different from monitoring the PVE job that originally created and uploaded the backup.

Understanding that distinction makes PBS backup information much easier to interpret.

Backup summary

Proxmox Extended Sensors can provide a summary of the backups stored in a datastore.

This gives Home Assistant a high-level view of the backup content currently available on PBS without requiring every stored snapshot to become an individual Home Assistant entity.

The summary is useful for understanding the overall state of the datastore while keeping the entity model manageable.

Backup errors

Backup error information reflects problems detected in the backup information available from PBS.

It should not be interpreted as a universal counter for every failed PVE backup job.

A PVE backup task can fail before a valid backup reaches PBS.

In that situation, the existing backups stored on PBS can remain healthy even though the PVE job itself failed.

For PVE-side failed tasks and backup health information, use the appropriate PVE or Cluster monitoring instead of treating the PBS datastore as the source of the original job result.

Last backup

The integration can expose information about the latest backup available in a datastore, including supported information such as:

• time of the latest backup;
• backup size;
• backup status.

These values are useful together.

A recent timestamp tells you when the latest stored backup was created, while size and status provide additional context about that backup.

Verified backups

When PBS reports verification information, it can provide confidence that the stored backup data has passed the corresponding PBS verification process.

Verification and creation are different operations.

A backup being present does not by itself mean that it has been verified, and a successful verification does not mean that every future backup job will succeed.

Treat verification as information about stored backup integrity rather than as a prediction of future backup operations.

Backup age matters

For many environments, the most important backup question is not simply whether backups exist, but whether a sufficiently recent backup exists.

A datastore containing many old backups can still represent a problem if the expected recent backup has not arrived.

Home Assistant can use latest-backup information to help surface situations where the stored backup history is becoming older than expected.

Read backup information together

Backup count, latest backup time, size, status and verification information describe different parts of the same backup environment.

As with node monitoring, they are most useful when interpreted together rather than treating a single value as a complete health assessment.

For the complete list of PBS backup entities, see Reference.

Maintenance

Proxmox Backup Server requires maintenance operations to keep backup storage healthy and manageable.

Proxmox Extended Sensors can expose maintenance status and supported actions in Home Assistant, allowing PBS maintenance to become part of dashboards and automation workflows.

Garbage Collection

Garbage Collection removes datastore chunks that are no longer required by referenced backups according to PBS behaviour.

Proxmox Extended Sensors can expose Garbage Collection information and provide a supported action to start GC for a datastore.

GC is not the same as deleting backups.

It operates on datastore data after backup retention and other PBS operations have determined which data is no longer referenced.

Prune

Prune applies the retention policy defined by a configured PBS Prune Job.

When a Prune Job is available for the datastore, Proxmox Extended Sensors can expose its status and provide a supported action to run that configured job.

The integration does not invent a retention policy.

The retention rules belong to the PBS Prune Job configured on the server.

Home Assistant simply provides another way to trigger the supported operation.

Verify

Verification checks stored backup data according to the configured PBS Verify Job.

When a Verify Job is configured, Proxmox Extended Sensors can expose verification status and provide a supported action to run that job.

Verification can be particularly useful as part of a scheduled backup-maintenance workflow because creating a backup and checking the integrity of stored backup data are separate concerns.

Sync

When a PBS Sync Job exists, Proxmox Extended Sensors can expose a supported action to run it.

Sync operations are defined by PBS.

The integration triggers the configured job rather than creating or redefining its source, destination or synchronization policy.

Maintenance actions and permissions

Being able to monitor PBS does not automatically mean that the configured account can execute maintenance operations.

GC, Prune, Verify and Sync actions depend on the permissions granted to the PBS account and API Token.

If maintenance information is visible but an action fails, check permissions before assuming that the monitoring connection itself is broken.

Automation workflows

PBS actions can be incorporated into Home Assistant automations.

For example, a workflow can trigger a configured maintenance operation according to your own schedule or conditions and then use PBS task or status information to monitor the result.

Automation should complement the PBS configuration rather than replace it.

Retention rules, Verify Jobs and Sync Jobs should remain defined in PBS, while Home Assistant can coordinate when supported operations are requested and how their results are surfaced.

Use maintenance actions deliberately, particularly on production backup storage.

For the complete list of supported PBS actions and maintenance entities, see Reference.

Tasks

PBS tasks provide operational context about work performed by the backup server.

They complement datastore and backup information by showing what PBS has recently been doing and whether those operations completed successfully.

Last task

Proxmox Extended Sensors can expose information about the latest PBS task available to the integration.

Depending on the information returned by PBS, this can include:

• task type;
• task status;
• duration;
• result or message.

These values help explain recent activity without requiring the user to open the PBS task history for every routine operation.

Task type

The task type identifies the kind of operation PBS performed.

This provides context for the result.

A successful Garbage Collection task and a successful Verify task both represent successful operations, but they describe completely different maintenance activity.

Task status

Task status indicates the reported result of the PBS operation.

This can be useful for dashboards and particularly for notifications when a maintenance operation does not complete as expected.

A failed task should be interpreted together with its type and available message rather than as an isolated failure flag.

Duration

Task duration can provide useful operational context.

Changes in duration do not automatically indicate a problem, but unusually long operations can be worth investigating when compared with the normal behaviour of the same type of task.

Datastore size, workload and the type of operation can all influence how long a PBS task takes.

Last action

The integration can also retain information about the latest supported PBS action initiated through Proxmox Extended Sensors.

This helps associate Home Assistant-triggered maintenance activity with the datastore where the operation was requested.

It is useful for understanding what Home Assistant most recently asked PBS to do, while the PBS task information provides the server-side operational result.

Tasks are not the same as PVE backup jobs

PBS task monitoring represents work performed or reported by PBS.

A backup job initiated by PVE belongs to a different operational context.

When diagnosing a failed backup, determine first whether the failure occurred in the PVE job, during communication or upload, or in a PBS-side operation.

This avoids drawing conclusions from the wrong task source.

For the complete list of PBS task entities, see Reference.

Troubleshooting

PBS issues are easier to diagnose when the problem is first separated into connection, permissions, datastore information, backup information or maintenance actions.

Do not assume that missing server-level information means that the entire PBS connection has failed.

The integration cannot connect to PBS

If the PBS connection cannot be created, verify:

• the PBS host;
• network connectivity from Home Assistant;
• the complete PBS user and realm;
• Token ID;
• Token Secret;
• certificate or SSL settings applicable to the connection.

PBS V5 authentication uses API Token credentials.

Remember that User, Token ID and Token Secret are separate values.

If the API Token has been recreated, update Home Assistant with the new secret.

Authentication succeeds but information is missing

Successful authentication does not guarantee access to every PBS endpoint.

Check the permissions granted to the dedicated PBS account and API Token.

Monitoring and maintenance actions may require different levels of access.

If some datastore information works while particular actions or task information do not, permissions are one of the first things to check.

Hosted PBS exposes limited information

Hosted or multi-tenant PBS providers can intentionally restrict access to server-level information.

You may have complete access to your datastore and backups without access to low-level server health or hardware information.

This does not automatically indicate an integration error.

Compare the missing information with what your provider actually exposes through its PBS API and account permissions.

A datastore does not appear

Confirm that the datastore is visible to the configured PBS account.

If multiple PBS servers are configured, also confirm that you are inspecting the correct Home Assistant PBS connection.

A datastore belongs to the PBS server that exposes it; similarly named datastores on different servers should not be treated as the same resource.

Datastore usage and backup state seem contradictory

Capacity information and backup health describe different things.

A datastore can have free space while a particular operation fails for another reason.

Likewise, all backups currently stored on PBS can be healthy even when a new PVE backup job has failed before completion.

Check the originating PVE task when diagnosing backup creation failures and use PBS information to understand the state of the backup server and the data actually stored there.

Backup errors show zero after a failed PVE job

This can be expected.

PBS backup information describes the backups available to PBS.

If a PVE backup fails before a completed backup is stored, the existing PBS backups can remain valid and the PBS-side backup error information does not become a counter for the failed PVE job.

Check PVE or Cluster task/backup monitoring for the originating job failure.

A maintenance button does not work

If GC, Prune, Verify or Sync monitoring is visible but the corresponding action fails, verify the PBS permissions of the configured account and API Token.

For Prune, Verify and Sync, also confirm that the corresponding PBS job exists and is correctly configured.

These actions execute configured PBS operations; Home Assistant does not create the missing PBS job automatically.

Sync is not available

Sync requires a corresponding PBS Sync Job.

If no Sync Job is available for the datastore or server configuration, there may be no Sync action for the integration to execute.

Configure and validate the Sync Job in PBS first.

Prune or Verify is not available

Prune and Verify actions rely on the corresponding configured PBS jobs.

Confirm that the expected job exists in PBS and applies to the datastore you are monitoring.

The integration triggers the configured job rather than creating one on demand.

Task information is unavailable

Task visibility depends on the information and permissions available through PBS.

If datastore monitoring works but task information is missing, verify that the configured account can access the required task information.

Hosted providers can also restrict operational information that would normally be available on a locally managed PBS server.

Check Home Assistant logs

When the cause is not obvious, open:

Settings → System → Logs

Look for entries related to Proxmox Extended Sensors around the time the PBS problem occurred.

Permission errors, unavailable endpoints and connection failures can provide useful diagnostic information.

Remove API Token secrets, credentials and other sensitive information before sharing logs publicly.

Before opening an issue

Try to identify whether the problem affects:

• the complete PBS connection;
• server health information;
• one datastore;
• backup information;
• a maintenance operation;
• task information;
• or a hosted-provider limitation.

Include the relevant Proxmox Extended Sensors version, Home Assistant version and PBS version when reporting a reproducible problem.

For hosted PBS, also mention that the service is provider-managed when that distinction is relevant.

Never include passwords or API Token secrets.

If the problem persists after these checks, use the project's GitHub issue tracker.