all lists on lists.proxmox.com
 help / color / mirror / Atom feed
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




  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 an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal