[pve-devel] [PATCH docs] backup: warn that tar does not honor exclusion pattern with a trailing slash

[Fiona Ebner]

As reported in the community forum [0], for tar, an exclusion pattern
with a trailing slash will not match a folder with that name. For
rsync and proxmox-backup-client however, such a pattern will exclude
a directory with that name, but not a file.

rsync is used for 'suspend' mode backup and tar is used for all
non-PBS backups to create the archive. So currently, in the presence
of an exclusion pattern with a trailing slash, there is inconsistency
between different backup modes (because for 'suspend' mode, rsync will
already do the exclusion too) as well as between PBS and non-PBS
backups.

There doesn't seem to be a straight-forward way to align the behavior
for tar with command-line options exactly. The trailing slash can't be
removed from the pattern, because that would also match files.
Matching with
> some/pattern/*
> some/pattern/.*
rather than
> some/pattern/
gets pretty close, which was suggested by Dominik. Just the empty
directory is still included.

In any case, modifying current behavior would be a breaking change, so
actually aligning the exclusion (more closely) is better done in the
next major release.

Signed-off-by: Fiona Ebner <f.ebner at proxmox.com>
---
 vzdump.adoc | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/vzdump.adoc b/vzdump.adoc
index 79d4bbc..3918e9a 100644
--- a/vzdump.adoc
+++ b/vzdump.adoc
@@ -578,6 +578,12 @@ You can also manually specify (additional) exclude paths, for example:
 excludes the directory `/tmp/` and any file or directory named `/var/foo`,
 `/var/foobar`, and so on.
 
+WARNING: For backups to Proxmox Backup Server (PBS) and `suspend` mode backups,
+patterns with a trailing slash will match directories, but not files. On the
+other hand, for non-PBS `snapshot` mode and `stop` mode backups, patterns with a
+trailing slash currently do not match at all, because the `tar` command does not
+support that.
+
 Paths that do not start with a `/` are not anchored to the container's root,
 but will match relative to any subdirectory. For example:
 
-- 
2.39.2