From: Jakob-Tobias Winter <tobias@stuttgart.de>
To: pbs-devel@lists.proxmox.com
Cc: Jakob-Tobias Winter <tobias@stuttgart.de>
Subject: [RFC PATCH proxmox-backup 07/12] docs: describe snapshot attributes and the tape job attribute filter
Date: Fri, 13 Nov 2026 09:56:34 +0100 [thread overview]
Message-ID: <20261113085637.57360-10-tobias@stuttgart.de> (raw)
In-Reply-To: <20261113085637.57360-3-tobias@stuttgart.de>
Explain what snapshot attributes are, where they are stored and who
can read them, which attributes Proxmox VE sets, and how to select
backup groups by them in a tape backup job.
Signed-off-by: Jakob-Tobias Winter <tobias@stuttgart.de>
---
docs/pve-integration.rst | 23 +++++++++++++++++++++++
docs/tape-backup.rst | 27 +++++++++++++++++++++++++++
docs/terminology.rst | 33 +++++++++++++++++++++++++++++++++
3 files changed, 83 insertions(+)
diff --git a/docs/pve-integration.rst b/docs/pve-integration.rst
index e3a91af39..860a34f4e 100644
--- a/docs/pve-integration.rst
+++ b/docs/pve-integration.rst
@@ -67,3 +67,26 @@ device within the environment (see `Proxmox VE Admin Guide: Backup and Restore
<https://pve.proxmox.com/pve-docs/pve-admin-guide.html#chapter_vzdump>`_.
+.. _pve_snapshot_attributes:
+
+Guest Tags and Resource Pool
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+When `Proxmox VE`_ backs up a guest, it stores the tags and the resource pool
+of the guest as :ref:`attributes <term_snapshot_attributes>` of the new backup
+snapshot:
+
+* ``pve-tag`` has one value for each tag of the guest.
+* ``pve-pool`` has the resource pool of the guest as its value. For a guest in
+ a nested pool, each parent pool is a value as well: a guest in the pool
+ ``customers/acme`` has the values ``customers/acme`` and ``customers``.
+
+The backup server does not interpret these attributes, but they can be used to
+select backups. For example, a :ref:`tape backup job <tape_backup_job_config>`
+can write the guests tagged ``prod`` to another media pool than the remaining
+guests. Selecting by a pool also covers the guests of the pools nested in it.
+
+.. note:: The attributes are stored unencrypted, also for encrypted backups. If
+ the tags and the resource pool of the guests should not be known to the
+ backup server, disable the ``pbs-snapshot-attributes`` option of the backup
+ jobs in Proxmox VE.
diff --git a/docs/tape-backup.rst b/docs/tape-backup.rst
index a22606909..8ac459235 100644
--- a/docs/tape-backup.rst
+++ b/docs/tape-backup.rst
@@ -742,6 +742,33 @@ backup. You can specify a single namespace with ``ns`` and a depth with
If no `max-depth` is given, it will include all recursive namespaces.
+Backup groups can be selected by their :ref:`attributes
+<term_snapshot_attributes>` with the ``attribute-filter`` option. For example,
+to only include the guests which have the tag ``prod`` in Proxmox VE:
+
+.. code-block:: console
+
+ # proxmox-tape backup-job update job2 --attribute-filter pve-tag=prod
+
+A filter matches a group if its value is one of the values the group has for
+the key. With several filters, a group is included if at least one of them
+matches. Prepend ``exclude:`` to a filter to skip the groups it matches. For
+example, to include all guests which are neither tagged ``prod`` nor ``test``:
+
+.. code-block:: console
+
+ # proxmox-tape backup-job update job3 --attribute-filter exclude:pve-tag=prod \
+ --attribute-filter exclude:pve-tag=test
+
+This allows writing guests to different media pools, depending on their tags or
+their resource pool, by using one job for each media pool.
+
+The attributes of a group are those of its newest snapshot which has
+attributes. A newer snapshot without attributes, for example from a client
+which does not set them, does not change them. A group which never got
+attributes is only included by jobs without a filter or with exclude filters
+only.
+
.. image:: images/screenshots/pbs-gui-tape-backup-jobs-add.png
:target: _images/pbs-gui-tape-backup-jobs-add.png
:align: right
diff --git a/docs/terminology.rst b/docs/terminology.rst
index 7ba8910cf..dcac79b31 100644
--- a/docs/terminology.rst
+++ b/docs/terminology.rst
@@ -130,3 +130,36 @@ As you can see, the time format is RFC3339_ with Coordinated
Universal Time (UTC_, identified by the trailing *Z*).
+.. _term_snapshot_attributes:
+
+Snapshot Attributes
+-------------------
+
+A backup snapshot can have attributes. They carry information about the source
+of a backup, which the backup server cannot know on its own, and can be used to
+select backups, for example in a :ref:`tape backup job
+<tape_backup_job_config>`. An attribute is a key with a list of values.
+
+.. code-block:: console
+ :caption: Snapshot Attribute Examples
+
+ pve-tag=prod
+ pve-tag=web
+ pve-pool=customer1
+
+In this example, the key ``pve-tag`` has the values ``prod`` and ``web``. Each
+value is stored on its own, a list of values is never joined into one string.
+
+A key consists of up to 32 lowercase letters, digits and ``-`` and starts with
+a letter. A value consists of up to 128 letters, digits and the characters
+``.``, ``_``, ``+``, ``/`` and ``-``.
+
+The attributes of a snapshot are set by the client after the backup has
+finished. Setting them replaces all attributes the snapshot had before. They
+are stored in the unprotected part of the manifest, so they are neither signed
+nor encrypted. Everyone who is allowed to see a snapshot can read its
+attributes, also if the backup itself is encrypted. They are kept when a
+snapshot is synced to another datastore or written to tape.
+
+`Proxmox VE`_ uses attributes to store the tags and the resource pool of a
+guest, see :ref:`pve_snapshot_attributes`.
--
2.53.0
next prev parent reply other threads:[~2026-11-13 9:06 UTC|newest]
Thread overview: 25+ messages / expand[flat|nested] mbox.gz Atom feed top
2026-11-13 8:56 [RFC PATCH many 00/12] snapshot attributes for tags and pools of PVE guests, tape job filter Jakob-Tobias Winter
2026-11-13 8:56 ` [RFC PATCH proxmox 01/12] pbs-api-types: add types and schemas for snapshot attributes Jakob-Tobias Winter
2026-11-16 14:57 ` Christian Ebner
2026-11-18 12:54 ` Samuel Rufinatscha
2026-11-13 8:56 ` [RFC PATCH proxmox 02/12] pbs-api-types: tape: add attribute filter to backup jobs Jakob-Tobias Winter
2026-11-16 14:57 ` Christian Ebner
2026-11-13 8:56 ` [RFC PATCH proxmox-backup 03/12] datastore: add attributes to backup snapshots Jakob-Tobias Winter
2026-11-16 14:57 ` Christian Ebner
2026-11-18 12:55 ` Samuel Rufinatscha
2026-11-13 8:56 ` [RFC PATCH proxmox-backup 04/12] fix #7452: api: datastore: add endpoints for snapshot attributes Jakob-Tobias Winter
2026-11-16 14:57 ` Christian Ebner
2026-11-13 8:56 ` [RFC PATCH proxmox-backup 05/12] tape: backup job: allow selecting groups by " Jakob-Tobias Winter
2026-11-18 13:06 ` Samuel Rufinatscha
2026-11-18 15:19 ` Christian Ebner
2026-11-13 8:56 ` [RFC PATCH proxmox-backup 06/12] ui: tape backup job: add attribute filter Jakob-Tobias Winter
2026-11-13 8:56 ` Jakob-Tobias Winter [this message]
2026-11-13 8:56 ` [RFC PATCH storage 08/12] pbs: add helper to set the attributes of a backup snapshot Jakob-Tobias Winter
2026-11-13 8:56 ` [RFC PATCH guest-common 09/12] vzdump: add pbs-snapshot-attributes option Jakob-Tobias Winter
2026-11-13 8:56 ` [RFC PATCH manager 10/12] vzdump: store guest tags and pool as snapshot attributes on PBS Jakob-Tobias Winter
2026-11-13 8:56 ` [RFC PATCH manager 11/12] ui: backup job: add selector for PBS snapshot attributes Jakob-Tobias Winter
2026-11-13 8:56 ` [RFC PATCH docs 12/12] vzdump: describe snapshot attributes on Proxmox Backup Server Jakob-Tobias Winter
2026-11-16 14:57 ` [RFC PATCH many 00/12] snapshot attributes for tags and pools of PVE guests, tape job filter Christian Ebner
2026-11-18 13:07 ` Samuel Rufinatscha
2026-11-18 14:22 ` Samuel Rufinatscha
2026-11-19 11:58 ` Jakob-Tobias Winter
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20261113085637.57360-10-tobias@stuttgart.de \
--to=tobias@stuttgart.de \
--cc=pbs-devel@lists.proxmox.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox