virt-back 0.2.4__tar.gz → 0.2.6__tar.gz

{virt-back-0.2.4 → virt_back-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: virt-back
-Version: 0.2.4
+Version: 0.2.6
 Summary: virt-back: A backup utility for QEMU, KVM, XEN, and Virtualbox guests
 Home-page: https://git.unturf.com/python/virt-back
 Author: Russell Ballestrini
@@ -9,6 +9,17 @@ License: Public Domain
 Keywords: backup virtual hypervisor QEMU KVM XEN Virtualbox
 Platform: All
 Description-Content-Type: text/markdown
+Requires-Dist: libvirt-python
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: platform
+Dynamic: requires-dist
+Dynamic: summary
 
 A backup utility for QEMU, KVM, XEN, and Virtualbox guests.
 
@@ -39,6 +50,7 @@ options:
   -g, --no-gzip         do not gzip the resulting tar file
   -a amount, --retention amount
                         backups to retain [default: 3]
+                        (applies to both rotated backup files AND ZFS @backup-* snapshots)
   -p 'PATH', --path 'PATH'
                         backup path [default: '/KVMBACK']
   -u 'URI', --uri 'URI'

{virt-back-0.2.4 → virt_back-0.2.6}/README.md

@@ -27,6 +27,7 @@ options:
   -g, --no-gzip         do not gzip the resulting tar file
   -a amount, --retention amount
                         backups to retain [default: 3]
+                        (applies to both rotated backup files AND ZFS @backup-* snapshots)
   -p 'PATH', --path 'PATH'
                         backup path [default: '/KVMBACK']
   -u 'URI', --uri 'URI'

virt_back-0.2.6/setup.py

@@ -0,0 +1,71 @@
+from setuptools import setup
+import os
+
+# Read the contents of your README file
+with open(os.path.join(os.path.dirname(__file__), "README.md"), encoding="utf-8") as f:
+    long_description = f.read()
+
+setup(
+    name="virt-back",
+    version="0.2.6",
+    description="virt-back: A backup utility for QEMU, KVM, XEN, and Virtualbox guests",
+    keywords="backup virtual hypervisor QEMU KVM XEN Virtualbox",
+    long_description=long_description,
+    long_description_content_type="text/markdown",
+    author="Russell Ballestrini",
+    author_email="russell@ballestrini.net",
+    url="https://git.unturf.com/python/virt-back",
+    platforms=["All"],
+    license="Public Domain",
+    py_modules=["virtback"],
+    include_package_data=True,
+    scripts=["virt-back"],
+    install_requires=[
+        "libvirt-python",
+    ],
+)
+
+# ---------------------------------------------------------------------------
+# Release process (automated via .gitlab-ci.yml on tag push)
+# ---------------------------------------------------------------------------
+#
+# Cutting a release:
+#   1. Bump `version=` above
+#   2. git commit -m "X.Y.Z: <one-line summary>"
+#   3. git tag -a X.Y.Z -m "X.Y.Z"
+#   4. git push origin master X.Y.Z
+#
+# The CI pipeline builds (python -m build) and uploads (twine upload) on the
+# tag push. No manual `python setup.py sdist && twine upload` needed.
+#
+# ---------------------------------------------------------------------------
+# Maintainer setup (one-time, per project) — required for CI uploads to work
+# ---------------------------------------------------------------------------
+#
+# git.unturf.com -> python/<this-project> -> Settings -> Repository ->
+#   Protected Tags -> "Protect tag":
+#     - Pattern:           *
+#     - Allowed to Create: Maintainers (match erldistpy's setting)
+#
+# This makes tags Protected refs, which lets the Protected/Masked
+# TWINE_USERNAME and TWINE_PASSWORD variables (set once at the python/
+# group level) reach the tag pipeline. Without Protected Tags, twine 6
+# falls through to OIDC trusted publishing and fails because PyPI's
+# self-hosted GitLab support is hardcoded to gitlab.com.
+#
+# Group variables live at:
+#   git.unturf.com -> python (group) -> Settings -> CI/CD -> Variables
+#   TWINE_USERNAME = __token__
+#   TWINE_PASSWORD = <pypi-AgEI...>   (Masked + Protected)
+#
+# setuptools keyword args: http://peak.telecommunity.com/DevCenter/setuptools
+
+# Installation Instructions:
+# To install virt-back, you can use pip:
+#  * pip install virt-back
+#
+# Note: You need to have the libvirt development libraries installed.
+# On Fedora/RedHat, you can install it with:
+#  * sudo dnf install libvirt-devel
+# On Ubuntu, you can install it with:
+#  * sudo apt-get install libvirt-dev

{virt-back-0.2.4 → virt_back-0.2.6}/virt-back

@@ -23,6 +23,7 @@ import libvirt
 import tarfile
 import syslog
 import re
+import glob
 from time import sleep
 from datetime import date
 from sys import exit
@@ -195,6 +196,9 @@ def backup(doms):
                 except subprocess.CalledProcessError as e:
                     logit("error", f"Failed to send ZFS snapshot {zfs_snapshot}: {e}")
                     continue
+
+                # Prune old @backup-* snapshots, keep newest `retention`
+                prune_zfs_snapshots(zfs_dataset, options.retention)
             else:
                 # Handle QCOW2 or other file-based disk
                 logit("backup", f"{disk_source} is not a ZFS dataset")
@@ -281,6 +285,48 @@ def is_zfs_dataset(disk_source):
         return False
 
 
+def prune_zfs_snapshots(zfs_dataset, retention):
+    """List @backup-* snapshots on dataset, destroy oldest until count <= retention.
+
+    Only touches snapshots virt-back created (@backup-* prefix). Never destroys
+    user or TrueNAS periodic snapshots. Never destroys more than necessary —
+    `retention` snapshots always survive as the recovery floor.
+    """
+    if retention < 1:
+        logit("error", f"retention must be >= 1, got {retention} — skipping prune")
+        return
+
+    # INVARIANT: reclamation eats from the tail (oldest first).
+    # `-s creation` sorts ascending by the ZFS creation timestamp (epoch
+    # precision, immune to TODAY timezone drift), so snaps[:surplus] below
+    # always slices the OLDEST entries. Never reorder this — destroying
+    # newer snapshots first would wipe the recovery floor while leaving
+    # stale tails behind.
+    try:
+        result = subprocess.run(
+            ["zfs", "list", "-t", "snapshot", "-H", "-o", "name",
+             "-s", "creation", zfs_dataset],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True, text=True,
+        )
+    except subprocess.CalledProcessError as e:
+        logit("error", f"Failed to list snapshots for {zfs_dataset}: {e}")
+        return
+
+    prefix = f"{zfs_dataset}@backup-"
+    snaps = [line for line in result.stdout.splitlines() if line.startswith(prefix)]
+
+    surplus = len(snaps) - retention
+    if surplus <= 0:
+        return
+
+    for snap in snaps[:surplus]:
+        logit("backup", f"pruning old ZFS snapshot {snap} (retention={retention})")
+        try:
+            subprocess.run(["zfs", "destroy", snap], check=True)
+        except subprocess.CalledProcessError as e:
+            logit("error", f"Failed to destroy snapshot {snap}: {e}")
+
+
 def shutdown(doms, wait=180):
     """Accept a list of dom objects, attempt to shutdown the active ones"""
     # get all running guests from list and invoke shutdown
@@ -401,7 +447,13 @@ def logit(context, message, quiet=False):
 
 
 def rotate(target, retention=3):
-    """file rotation routine"""
+    """file rotation routine — shift within window then reap any stale files
+    at indices >= retention.
+
+    Without the reap step, lowering retention (e.g. 5 -> 2) leaves orphan
+    .2, .3, .4 around forever — the same accumulation pattern that ZFS
+    snapshots had before 0.2.5.
+    """
     for i in range(retention - 2, 0, -1):  # count backwards
         old_name = "%s.%s" % (target, i)
         new_name = "%s.%s" % (target, i + 1)
@@ -411,6 +463,22 @@ def rotate(target, retention=3):
             pass
     move(target, target + ".1")
 
+    # Reap files at indices >= retention. INVARIANT: never touches the
+    # current target (no numeric suffix) and never touches indices in
+    # [1, retention-1] (the active rotation window).
+    for stale in glob.glob("%s.*" % target):
+        suffix = stale.rsplit(".", 1)[-1]
+        try:
+            idx = int(suffix)
+        except ValueError:
+            continue  # not a rotation index (e.g., backup.tar.gz where .gz isn't int)
+        if idx >= retention:
+            logit("backup", "removing stale backup file %s (retention=%s)" % (stale, retention))
+            try:
+                remove(stale)
+            except OSError as e:
+                logit("error", "failed to remove %s: %s" % (stale, e))
+
 
 def getoptions():
     """Fetch cli args, parse and map to python, test sanity"""

{virt-back-0.2.4 → virt_back-0.2.6}/virt_back.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: virt-back
-Version: 0.2.4
+Version: 0.2.6
 Summary: virt-back: A backup utility for QEMU, KVM, XEN, and Virtualbox guests
 Home-page: https://git.unturf.com/python/virt-back
 Author: Russell Ballestrini
@@ -9,6 +9,17 @@ License: Public Domain
 Keywords: backup virtual hypervisor QEMU KVM XEN Virtualbox
 Platform: All
 Description-Content-Type: text/markdown
+Requires-Dist: libvirt-python
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: keywords
+Dynamic: license
+Dynamic: platform
+Dynamic: requires-dist
+Dynamic: summary
 
 A backup utility for QEMU, KVM, XEN, and Virtualbox guests.
 
@@ -39,6 +50,7 @@ options:
   -g, --no-gzip         do not gzip the resulting tar file
   -a amount, --retention amount
                         backups to retain [default: 3]
+                        (applies to both rotated backup files AND ZFS @backup-* snapshots)
   -p 'PATH', --path 'PATH'
                         backup path [default: '/KVMBACK']
   -u 'URI', --uri 'URI'

{virt-back-0.2.4 → virt_back-0.2.6}/virtback.py

@@ -23,6 +23,7 @@ import libvirt
 import tarfile
 import syslog
 import re
+import glob
 from time import sleep
 from datetime import date
 from sys import exit
@@ -195,6 +196,9 @@ def backup(doms):
                 except subprocess.CalledProcessError as e:
                     logit("error", f"Failed to send ZFS snapshot {zfs_snapshot}: {e}")
                     continue
+
+                # Prune old @backup-* snapshots, keep newest `retention`
+                prune_zfs_snapshots(zfs_dataset, options.retention)
             else:
                 # Handle QCOW2 or other file-based disk
                 logit("backup", f"{disk_source} is not a ZFS dataset")
@@ -281,6 +285,48 @@ def is_zfs_dataset(disk_source):
         return False
 
 
+def prune_zfs_snapshots(zfs_dataset, retention):
+    """List @backup-* snapshots on dataset, destroy oldest until count <= retention.
+
+    Only touches snapshots virt-back created (@backup-* prefix). Never destroys
+    user or TrueNAS periodic snapshots. Never destroys more than necessary —
+    `retention` snapshots always survive as the recovery floor.
+    """
+    if retention < 1:
+        logit("error", f"retention must be >= 1, got {retention} — skipping prune")
+        return
+
+    # INVARIANT: reclamation eats from the tail (oldest first).
+    # `-s creation` sorts ascending by the ZFS creation timestamp (epoch
+    # precision, immune to TODAY timezone drift), so snaps[:surplus] below
+    # always slices the OLDEST entries. Never reorder this — destroying
+    # newer snapshots first would wipe the recovery floor while leaving
+    # stale tails behind.
+    try:
+        result = subprocess.run(
+            ["zfs", "list", "-t", "snapshot", "-H", "-o", "name",
+             "-s", "creation", zfs_dataset],
+            stdout=subprocess.PIPE, stderr=subprocess.PIPE, check=True, text=True,
+        )
+    except subprocess.CalledProcessError as e:
+        logit("error", f"Failed to list snapshots for {zfs_dataset}: {e}")
+        return
+
+    prefix = f"{zfs_dataset}@backup-"
+    snaps = [line for line in result.stdout.splitlines() if line.startswith(prefix)]
+
+    surplus = len(snaps) - retention
+    if surplus <= 0:
+        return
+
+    for snap in snaps[:surplus]:
+        logit("backup", f"pruning old ZFS snapshot {snap} (retention={retention})")
+        try:
+            subprocess.run(["zfs", "destroy", snap], check=True)
+        except subprocess.CalledProcessError as e:
+            logit("error", f"Failed to destroy snapshot {snap}: {e}")
+
+
 def shutdown(doms, wait=180):
     """Accept a list of dom objects, attempt to shutdown the active ones"""
     # get all running guests from list and invoke shutdown
@@ -401,7 +447,13 @@ def logit(context, message, quiet=False):
 
 
 def rotate(target, retention=3):
-    """file rotation routine"""
+    """file rotation routine — shift within window then reap any stale files
+    at indices >= retention.
+
+    Without the reap step, lowering retention (e.g. 5 -> 2) leaves orphan
+    .2, .3, .4 around forever — the same accumulation pattern that ZFS
+    snapshots had before 0.2.5.
+    """
     for i in range(retention - 2, 0, -1):  # count backwards
         old_name = "%s.%s" % (target, i)
         new_name = "%s.%s" % (target, i + 1)
@@ -411,6 +463,22 @@ def rotate(target, retention=3):
             pass
     move(target, target + ".1")
 
+    # Reap files at indices >= retention. INVARIANT: never touches the
+    # current target (no numeric suffix) and never touches indices in
+    # [1, retention-1] (the active rotation window).
+    for stale in glob.glob("%s.*" % target):
+        suffix = stale.rsplit(".", 1)[-1]
+        try:
+            idx = int(suffix)
+        except ValueError:
+            continue  # not a rotation index (e.g., backup.tar.gz where .gz isn't int)
+        if idx >= retention:
+            logit("backup", "removing stale backup file %s (retention=%s)" % (stale, retention))
+            try:
+                remove(stale)
+            except OSError as e:
+                logit("error", "failed to remove %s: %s" % (stale, e))
+
 
 def getoptions():
     """Fetch cli args, parse and map to python, test sanity"""

virt-back-0.2.4/setup.py

@@ -1,47 +0,0 @@
-from setuptools import setup
-import os
-
-# Read the contents of your README file
-with open(os.path.join(os.path.dirname(__file__), "README.md"), encoding="utf-8") as f:
-    long_description = f.read()
-
-setup(
-    name="virt-back",
-    version="0.2.4",
-    description="virt-back: A backup utility for QEMU, KVM, XEN, and Virtualbox guests",
-    keywords="backup virtual hypervisor QEMU KVM XEN Virtualbox",
-    long_description=long_description,
-    long_description_content_type="text/markdown",
-    author="Russell Ballestrini",
-    author_email="russell@ballestrini.net",
-    url="https://git.unturf.com/python/virt-back",
-    platforms=["All"],
-    license="Public Domain",
-    py_modules=["virtback"],
-    include_package_data=True,
-    scripts=["virt-back"],
-    install_requires=[
-        "libvirt-python",
-    ],
-)
-
-"""
-setup()
-  keyword args: http://peak.telecommunity.com/DevCenter/setuptools
-
-# built and uploaded to pypi with this:
-
-python setup.py sdist
-twine upload dist/*
-
-"""
-
-# Installation Instructions:
-# To install virt-back, you can use pip:
-#  * pip install virt-back
-#
-# Note: You need to have the libvirt development libraries installed.
-# On Fedora/RedHat, you can install it with:
-#  * sudo dnf install libvirt-devel
-# On Ubuntu, you can install it with:
-#  * sudo apt-get install libvirt-dev