virt-back 0.2.3__tar.gz → 0.2.5__tar.gz

{virt-back-0.2.3 → virt_back-0.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: virt-back
-Version: 0.2.3
+Version: 0.2.5
 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.
 
@@ -24,49 +35,48 @@ https://git.unturf.com/python/virt-back
 **usage**
 
 ```
-root@guile[/mnt/downloads/virt-back]# ./virt-back --help
-Usage: virt-back [options]
-
-A backup utility for QEMU, KVM, XEN, and Virtualbox guests. Virt-back is a
-python application that uses the libvirt api to safely  shutdown, gzip, and
-restart guests.  The backup process logs to syslog for auditing and virt-back
-works great with cron for scheduling outages. Virt-back has been placed in the
-public domain and  the latest version may be downloaded here:
+virt-back --help
+usage: virt-back [-h] [-q] [-d] [-g] [-a amount] [-p 'PATH'] [-u 'URI'] [-i] [--info-all] [-b] [-r] [-s] [-c] [--backup-all] [--reboot-all] [--shutdown-all] [--create-all]
+
+A backup utility for QEMU, KVM, XEN, and Virtualbox guests. Virt-back is a python application that uses the libvirt api to safely shutdown, gzip, and restart guests. The backup process
+logs to syslog for auditing and virt-back works great with cron for scheduling outages. Virt-back has been placed in the public domain and the latest version may be downloaded here:
+
 https://git.unturf.com/python/virt-back
 
-Options:
+options:
   -h, --help            show this help message and exit
   -q, --quiet           prevent output to stdout
   -d, --date            append date to tar filename [default: no date]
   -g, --no-gzip         do not gzip the resulting tar file
-  -a amount, --retention=amount
+  -a amount, --retention amount
                         backups to retain [default: 3]
-  -p 'PATH', --path='PATH'
+                        (applies to both rotated backup files AND ZFS @backup-* snapshots)
+  -p 'PATH', --path 'PATH'
                         backup path [default: '/KVMBACK']
-  -u 'URI', --uri='URI'
+  -u 'URI', --uri 'URI'
                         optional hypervisor uri
 
-  Actions for info testing:
-    These options display info or test a list of guests.
+Actions for info testing:
+  These options display info or test a list of guests.
 
-    -i, --info          info/test a list of guests (space delimited dom names)
-    --info-all          attempt to show info on ALL guests
+  -i, --info            info/test a list of guests (space delimited dom names)
+  --info-all            attempt to show info on ALL guests
 
-  Actions for a list of dom names:
-    WARNING:  These options WILL bring down guests!
+Actions for a list of dom names:
+  WARNING: These options WILL bring down guests!
 
-    -b, --backup        backup a list of guests (space delimited dom names)
-    -r, --reboot        reboot a list of guests (space delimited dom names)
-    -s, --shutdown      shutdown a list of guests (space delimited dom names)
-    -c, --create        start a list of guests (space delimited dom names)
+  -b, --backup          backup a list of guests (space delimited dom names)
+  -r, --reboot          reboot a list of guests (space delimited dom names)
+  -s, --shutdown        shutdown a list of guests (space delimited dom names)
+  -c, --create          start a list of guests (space delimited dom names)
 
-  Actions for all doms:
-    WARNING:  These options WILL bring down ALL guests!
+Actions for all doms:
+  WARNING: These options WILL bring down ALL guests!
 
-    --backup-all        attempt to shutdown, backup, and start ALL guests
-    --reboot-all        attempt to shutdown and then start ALL guests
-    --shutdown-all      attempt to shutdown ALL guests
-    --create-all        attempt to start ALL guests
+  --backup-all          attempt to shutdown, backup, and start ALL guests
+  --reboot-all          attempt to shutdown and then start ALL guests
+  --shutdown-all        attempt to shutdown ALL guests
+  --create-all          attempt to start ALL guests
 ```
 
 

{virt-back-0.2.3 → virt_back-0.2.5}/README.md

@@ -12,49 +12,48 @@ https://git.unturf.com/python/virt-back
 **usage**
 
 ```
-root@guile[/mnt/downloads/virt-back]# ./virt-back --help
-Usage: virt-back [options]
-
-A backup utility for QEMU, KVM, XEN, and Virtualbox guests. Virt-back is a
-python application that uses the libvirt api to safely  shutdown, gzip, and
-restart guests.  The backup process logs to syslog for auditing and virt-back
-works great with cron for scheduling outages. Virt-back has been placed in the
-public domain and  the latest version may be downloaded here:
+virt-back --help
+usage: virt-back [-h] [-q] [-d] [-g] [-a amount] [-p 'PATH'] [-u 'URI'] [-i] [--info-all] [-b] [-r] [-s] [-c] [--backup-all] [--reboot-all] [--shutdown-all] [--create-all]
+
+A backup utility for QEMU, KVM, XEN, and Virtualbox guests. Virt-back is a python application that uses the libvirt api to safely shutdown, gzip, and restart guests. The backup process
+logs to syslog for auditing and virt-back works great with cron for scheduling outages. Virt-back has been placed in the public domain and the latest version may be downloaded here:
+
 https://git.unturf.com/python/virt-back
 
-Options:
+options:
   -h, --help            show this help message and exit
   -q, --quiet           prevent output to stdout
   -d, --date            append date to tar filename [default: no date]
   -g, --no-gzip         do not gzip the resulting tar file
-  -a amount, --retention=amount
+  -a amount, --retention amount
                         backups to retain [default: 3]
-  -p 'PATH', --path='PATH'
+                        (applies to both rotated backup files AND ZFS @backup-* snapshots)
+  -p 'PATH', --path 'PATH'
                         backup path [default: '/KVMBACK']
-  -u 'URI', --uri='URI'
+  -u 'URI', --uri 'URI'
                         optional hypervisor uri
 
-  Actions for info testing:
-    These options display info or test a list of guests.
+Actions for info testing:
+  These options display info or test a list of guests.
 
-    -i, --info          info/test a list of guests (space delimited dom names)
-    --info-all          attempt to show info on ALL guests
+  -i, --info            info/test a list of guests (space delimited dom names)
+  --info-all            attempt to show info on ALL guests
 
-  Actions for a list of dom names:
-    WARNING:  These options WILL bring down guests!
+Actions for a list of dom names:
+  WARNING: These options WILL bring down guests!
 
-    -b, --backup        backup a list of guests (space delimited dom names)
-    -r, --reboot        reboot a list of guests (space delimited dom names)
-    -s, --shutdown      shutdown a list of guests (space delimited dom names)
-    -c, --create        start a list of guests (space delimited dom names)
+  -b, --backup          backup a list of guests (space delimited dom names)
+  -r, --reboot          reboot a list of guests (space delimited dom names)
+  -s, --shutdown        shutdown a list of guests (space delimited dom names)
+  -c, --create          start a list of guests (space delimited dom names)
 
-  Actions for all doms:
-    WARNING:  These options WILL bring down ALL guests!
+Actions for all doms:
+  WARNING: These options WILL bring down ALL guests!
 
-    --backup-all        attempt to shutdown, backup, and start ALL guests
-    --reboot-all        attempt to shutdown and then start ALL guests
-    --shutdown-all      attempt to shutdown ALL guests
-    --create-all        attempt to start ALL guests
+  --backup-all          attempt to shutdown, backup, and start ALL guests
+  --reboot-all          attempt to shutdown and then start ALL guests
+  --shutdown-all        attempt to shutdown ALL guests
+  --create-all          attempt to start ALL guests
 ```
 
 

virt_back-0.2.5/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.5",
+    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.3 → virt_back-0.2.5}/virt-back

@@ -195,6 +195,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 +284,42 @@ 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
+
+    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

{virt-back-0.2.3 → virt_back-0.2.5}/virt_back.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.4
 Name: virt-back
-Version: 0.2.3
+Version: 0.2.5
 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.
 
@@ -24,49 +35,48 @@ https://git.unturf.com/python/virt-back
 **usage**
 
 ```
-root@guile[/mnt/downloads/virt-back]# ./virt-back --help
-Usage: virt-back [options]
-
-A backup utility for QEMU, KVM, XEN, and Virtualbox guests. Virt-back is a
-python application that uses the libvirt api to safely  shutdown, gzip, and
-restart guests.  The backup process logs to syslog for auditing and virt-back
-works great with cron for scheduling outages. Virt-back has been placed in the
-public domain and  the latest version may be downloaded here:
+virt-back --help
+usage: virt-back [-h] [-q] [-d] [-g] [-a amount] [-p 'PATH'] [-u 'URI'] [-i] [--info-all] [-b] [-r] [-s] [-c] [--backup-all] [--reboot-all] [--shutdown-all] [--create-all]
+
+A backup utility for QEMU, KVM, XEN, and Virtualbox guests. Virt-back is a python application that uses the libvirt api to safely shutdown, gzip, and restart guests. The backup process
+logs to syslog for auditing and virt-back works great with cron for scheduling outages. Virt-back has been placed in the public domain and the latest version may be downloaded here:
+
 https://git.unturf.com/python/virt-back
 
-Options:
+options:
   -h, --help            show this help message and exit
   -q, --quiet           prevent output to stdout
   -d, --date            append date to tar filename [default: no date]
   -g, --no-gzip         do not gzip the resulting tar file
-  -a amount, --retention=amount
+  -a amount, --retention amount
                         backups to retain [default: 3]
-  -p 'PATH', --path='PATH'
+                        (applies to both rotated backup files AND ZFS @backup-* snapshots)
+  -p 'PATH', --path 'PATH'
                         backup path [default: '/KVMBACK']
-  -u 'URI', --uri='URI'
+  -u 'URI', --uri 'URI'
                         optional hypervisor uri
 
-  Actions for info testing:
-    These options display info or test a list of guests.
+Actions for info testing:
+  These options display info or test a list of guests.
 
-    -i, --info          info/test a list of guests (space delimited dom names)
-    --info-all          attempt to show info on ALL guests
+  -i, --info            info/test a list of guests (space delimited dom names)
+  --info-all            attempt to show info on ALL guests
 
-  Actions for a list of dom names:
-    WARNING:  These options WILL bring down guests!
+Actions for a list of dom names:
+  WARNING: These options WILL bring down guests!
 
-    -b, --backup        backup a list of guests (space delimited dom names)
-    -r, --reboot        reboot a list of guests (space delimited dom names)
-    -s, --shutdown      shutdown a list of guests (space delimited dom names)
-    -c, --create        start a list of guests (space delimited dom names)
+  -b, --backup          backup a list of guests (space delimited dom names)
+  -r, --reboot          reboot a list of guests (space delimited dom names)
+  -s, --shutdown        shutdown a list of guests (space delimited dom names)
+  -c, --create          start a list of guests (space delimited dom names)
 
-  Actions for all doms:
-    WARNING:  These options WILL bring down ALL guests!
+Actions for all doms:
+  WARNING: These options WILL bring down ALL guests!
 
-    --backup-all        attempt to shutdown, backup, and start ALL guests
-    --reboot-all        attempt to shutdown and then start ALL guests
-    --shutdown-all      attempt to shutdown ALL guests
-    --create-all        attempt to start ALL guests
+  --backup-all          attempt to shutdown, backup, and start ALL guests
+  --reboot-all          attempt to shutdown and then start ALL guests
+  --shutdown-all        attempt to shutdown ALL guests
+  --create-all          attempt to start ALL guests
 ```
 
 

{virt-back-0.2.3 → virt_back-0.2.5}/virtback.py

@@ -195,6 +195,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 +284,42 @@ 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
+
+    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

virt-back-0.2.3/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.3",
-    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