zfs-auto-snapshot

Table of contents

• Introduction
  • Versions TLDR
• Roadmap
  • Future
    • Bash 5+ code cleanup and simplification for better readability, maintainability
    • Allow flags to explicitly set UTC, local, or specified time offset
    • Include a family of user-level ZFS snapshot helper scripts
    • Address relevant high-priority issues and PRs from original project
  • Items finished for v2.0.0
    • Better naming convention
    • Shebang changed from #!/bin/sh to #!/bin/bash
    • Added the minor deltas of the zfsonlinux version back in over debian apt version
    • Bash 3.2+ code cleanup and simplification for better readability, maintainability
• Installation
• Uninstallation
• Copyright and license

Introduction

Automatically create, rotate, and destroy periodic ZFS snapshots.

The original project this was forked from - via zfsonlinux page - is officially dead, unless it's revived somtime (now six+ years later). The last commit was 2019-09-25, as of the time this sentence was originally written on 2026-04-08.

The original project has a few trivial enhancements over the version installable via (e.g.) apt install zfs-auto-snapshot, but the script is mostly the same. If you have zfs-auto-snapshot installed via apt install, both OG github version and this one are newer and better - you should uninstall the one via apt:

This, in spite of the original script having some obvious minor bugs that even linters pick up on. (E.g. non-POSIX bashisms in a #!/bin/sh script.)

It's also time for an update to bring some freshness to the project. (See roadmap below.)

Confused about which version is which? Here's the...

Versions TLDR

• zfsonlinux: No official version #. The OG version. Officially dead as of 2019. Still works.

• Debian apt version: v1.2.4-1. Appears to be unmaintained (but available) since 2017. Still works.

• This version: The unique features of both previous versions, and modernized with the additional battle-tested features below.

Note: While some attempt may be made to address original open issues and PRs, the focus will remain on ZFS-On-Linux, and secondarily BSD. And only the Kernel module; in other words, the focus is not Darwin nor the legacy FUSE version. (Although this will likely continue to work fine with those, and does now.)

Roadmap

Future

Bash 5+ code cleanup and simplification for better readability, maintainability

Exploratory.

It's not a stretch to set Base 5 as a dependency. It's been widely available since 2020. BSD users get v5 for free when installing bash from their native repo, and macOS can be upgraded to Bash 5 with two command lines. (One to install brew, one to install bash.) In spite of this project not "officially" supporting macOS.

Allow flags to explicitly set UTC, local, or specified time offset

E.g. --utc, --local-time, or --time-offset=nnn

Include a family of user-level ZFS snapshot helper scripts

Examples:

• Create a manual snapshot with a filesystem and description. Script will prepend date/time in correct format, and properly escape and shorten description if necessary.
• Destroy snapshots based on a series of nestable --include='regex' and/or --exclude='regex' expressions as arguments, as well as --older-than=n arg (in date/time format or 'days' 'hours' etc. suffix).

Address relevant high-priority issues and PRs from original project

Items finished for v2.0.0

Better naming convention

• Instead of e.g.:

  • filesys@zfs-auto-snap_frequent_2026-04-08-0259, in UTC time, you get:
  • filesys@20260408-195930_zfs-auto-snap_frequent in local time.

• Benefits:

  • More natural sorting by date/time of snapshots, when sorted by name.
  • UTC time, with the same updated format, can still be specified in the script with existing constant.
  • Manual snapshots with same convention will also be sorted correctly, e.g. when named something like:
    • filesys@20260408-195945_my-manual-important-snapshot

Shebang changed from #!/bin/sh to #!/bin/bash

• This is to immediately fix a bug in the original script, where the sh shebang is incompatible with variables declared with local.
• Ongoing, will allow for cleanup of unnecessarily convoluted POSIX syntax, and potentially more powerful features in the future.

Added the minor deltas of the zfsonlinux version back in (over debian apt version)

The (now dead) version this was forked from, while it enhances features and compatibility on Linux as noted above, goes slightly backwards by just a few lines of code, when diff-compared to zfsonlinux's github version. The latter detects zero-size snapshots, and adds Darwin compatibility. (Though the latter is explicitly not a goal of this fork, in part since ZFS development for Darwin lags significantly behind Linux.) But those lines will be added back in so that the main script is is a 1:1 ancestral fork.

Bash 3.2+ code cleanup and simplification for better readability, maintainability

Bash 3.2+ allows for idiomatic language improvements, more compact syntactic sugar, and safety - compared to legacy POSIX-only.

Bash 3.2 is the last target available on macOS Darwin, unless you install the latest Bash (v5) - via ports or brew.

Installation

This is the preferred way to install, because it includes the man and cron files.

If you just download the single file from the latest stable release, you don't get that. The version on main is always the latest stable (not dev) version.

## Remove package-installed version if installed - or via rpm, pacman, etc.
sudo apt purge zfs-auto-snapshot
[[ -d /sbin/zfs-auto-snapshot ]] && sudo rm /sbin/zfs-auto-snapshot

## Install this improved version
cd $(mktemp -d)
git clone git@github.com:jim-collier/zfs-auto-snapshot.git
cd zfs-auto-snapshot
sudo make install

Uninstallation

## Remove this version
[[ -d /sbin/zfs-auto-snapshot ]] && sudo rm /sbin/zfs-auto-snapshot

## Reinstall package version - or via rpm, pacman, etc.
sudo apt install --reinstall zfs-auto-snapshot

Copyright and license

Copyright © 2011 Darik Horn dajhorn@vanadac.com
Copyright © 2026 Jim Collier [ID: 2უNაɘ«҂թȹɤξπ๙¿ձϖ]
→ Changes documented above, and in changlog.md
Licensed under the GNU GPL v2. No warranty.