public inbox for pbs-devel@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 a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
Service provided by Proxmox Server Solutions GmbH | Privacy | Legal