Rev 55 | Blame | Compare with Previous | Last modification | View Log | Download | RSS feed
## cleanSnaps
Clean old ZFS snapshots whose names include a TTL suffix. This document describes usage, accepted snapshot name patterns, options, examples and notes.
**Version:** 1.1
**Author:** R. W. Rodlico
**License:** Simplified BSD License (FreeBSD License)
### Purpose
`cleanSnaps` is a small Perl utility that scans a list of ZFS snapshots and removes or reports snapshots that have exceeded their configured TTL. TTLs are encoded in snapshot names as a numeric suffix plus a unit (s, m, h, d, w, y). The script supports date/time-stamped snapshot names and an optional time-shift for testing.
### Location
Script: `cleanSnaps` (same directory as this file)
### Synopsis
```
cleanSnaps [--force|-f] [--verbose|-v] [--timeshift|-t <shift>] [--unmatched|-u] [--version|-V] [--help|-h] [pool]
```
- `--force, -f` — Actually destroy snapshots. By default the script runs in safe (non-destructive) mode and only reports candidate snapshots.
- `--verbose, -v` — Verbose logging; prints keep/skip messages and extra information.
- `--timeshift, -t <shift>` — Apply an artificial time-shift. The script accepts a signed or unsigned quantity with a unit (examples: `30d`, `-4w`, `+3d`, `3600s`). Units: s, m, h, d, w, y. Useful for testing TTL expiry without changing the system clock. A positive shift moves "now" forward (so more snapshots appear expired); a negative shift moves "now" backward. No sign assumed to be backwards.
- `--unmatched, -u` — ONLY clean snapshots that don't match the retention pattern. When this flag is set, normal retention/TTL processing is skipped entirely. Only snapshots that fail to match the expected date/time + TTL pattern (or have unparseable dates) are marked for removal. This is useful for cleaning up snapshots with incorrect naming conventions.
- `--version, -V` — Show version information and exit.
- `--help, -h` — Show help/usage and exit.
- `pool` (optional) — Restrict processing to snapshots whose pool name matches this string.
When called without a positional `pool` argument, the script will process snapshots from standard input or from a `zfs list` invocation performed by the script. (See the script headers and tests for details.)
### Snapshot name format
The script recognizes snapshots whose names contain a date stamp followed (optionally after arbitrary text) by a TTL token. The accepted date/time formats include:
- `YYYY-MM-DD` (e.g. `2025-12-15`)
- `YYYY-MM-DD_HH:MM:SS` or `YYYY-MM-DD_HH.MM.SS` (time portion may use `:` or `.` separators; the separator between date and time is an underscore)
The TTL suffix is a number followed by a unit letter:
- `s` — seconds
- `m` — minutes
- `h` — hours
- `d` — days
- `w` — weeks
- `y` — years
Examples of matching snapshot name fragments:
- `backup_2025-12-15_16.09.00_7d` — date/time + TTL 7 days
- `autosnap_2025-12-15_7h` — date + TTL 7 hours
- `daily_2025-12-15_30d_old` — optional trailing text after TTL is allowed; the TTL token (e.g. `30d`) is used to compute expiry.
The script tolerates arbitrary text between the date/time stamp and the TTL token.
### Matching regex
The script uses a single regular expression to identify date/time stamped snapshot names and their TTL token. The exact regex is:
```
/.*?(\d{4}-\d{2}-\d{2}(?:[T _]\d{2}[:\.]\d{2}(?:[:\.]\d{2})?)?)(?:.*?)(\d+)([smhdwy])$/
```
Explanation:
- The regex is applied to the snapshot name portion (the part after the `@` in a `dataset@snapshot` string).
- Capture group 1: the date or date-time stamp. Accepts `YYYY-MM-DD` or `YYYY-MM-DD_HH:MM`/`YYYY-MM-DD_HH.MM.SS` styles. The separator between date and time can be `T`, space, or underscore; time separators may be `:` or `.`.
- Capture group 2: the numeric TTL quantity (one or more digits).
- Capture group 3: the TTL unit, one of `s m h d w y` (seconds, minutes, hours, days, weeks, years).
- The regex allows arbitrary text between the date/time stamp and the TTL token, and requires the TTL token to be at the end of the snapshot name.
If a snapshot name does not match this pattern it will be ignored by `cleanSnaps` (unless the `--unmatched` flag is used).
### Behavior
**Normal mode (without --unmatched):**
- The script calculates the expiry time as the date/time parsed from the snapshot name plus the TTL interval. If the resulting expiry timestamp is earlier than the current time (adjusted by any `--timeshift`), the snapshot is considered expired and will be listed.
- Snapshots that don't match the pattern are skipped and reported in verbose mode.
- Use `--force` to perform destruction via `zfs destroy`.
**Unmatched mode (with --unmatched):**
- The script ONLY processes snapshots that fail to match the expected pattern.
- Normal retention/TTL logic is completely skipped for snapshots that match the pattern.
- Only snapshots with names that don't match the date/time + TTL regex (or have unparseable dates) are marked for removal.
- This mode is useful for cleaning up incorrectly named snapshots while preserving all properly formatted ones.
**Both modes:**
- The script prints actions it would take; in its default (safe) mode it only reports candidate snapshots. Use `--verbose` for additional keep/skip messages and context.
### Examples
**Normal retention mode:**
- Run with a 30-day backward time-shift (simulate time 30 days earlier, ie will retain an additional 30 days of snapshots):
```bash
cleanSnaps -t 30d # same as -30d
cleanSnaps -t 2592000 # equivalent (30 days in seconds)
```
- Actually remove all expired snapshots from pool tank, displaying each step:
```bash
cleanSnaps -f -v tank
```
- Restrict processing to pool `tank` (only snapshots whose pool prefix matches `tank` will be considered):
```bash
cleanSnaps tank
```
**Unmatched snapshot cleanup:**
- List all snapshots that don't match the expected naming pattern:
```bash
cleanSnaps -v -u
```
- Actually remove snapshots with incorrect names (useful for cleaning up after naming convention changes):
```bash
cleanSnaps -f -u tank
```
**Version and help:**
- Show version information:
```bash
cleanSnaps --version
cleanSnaps -V
```
- Show help:
```bash
cleanSnaps --help
cleanSnaps -h
```
### Safety & Notes
- The script includes a help flag and a Simplified BSD license header. It is safe by default (it reports candidates without destroying them). Nevertheless, exercise caution when running on production systems — prefer testing with `--timeshift` or sample input first.
- In normal mode, the script parses a variety of date/time formats but will ignore snapshot entries that do not match the expected patterns; those snapshots are left untouched.
- The `--unmatched` flag inverts this behavior: it ONLY targets snapshots that don't match the pattern, making it safe to use for cleaning up incorrectly named snapshots without affecting your properly formatted ones.
- The script depends on standard Perl modules available in most Perl 5 installations. See the script header for exact module imports.
- Always run without `--force` first to review what would be deleted.
### Tests
There is a test harness in the repository (see `cleanSnaps/test_cleanSnaps.pl`) which includes sample snapshot names covering date/time formats, dot/colon time separators, and the `h` (hour) TTL unit. The test suite includes:
1. **TEST 1**: Validates normal retention logic - snapshots are correctly kept or removed based on TTL
2. **TEST 2**: Validates `--unmatched` flag - only unmatched snapshots are removed, matched snapshots are skipped
3. **TEST 3**: Validates `--version` flag - version information is displayed correctly
Run the test with: `perl test_cleanSnaps.pl`
Use the test to validate behavior before running against real ZFS pools.
You can also include a filename which contains a list of snapshots and all tests will be run against that.
### Contributing / Changes
If you update the script, update this documentation to reflect new options, changes in the snapshot matching regex, or different behaviors for dry-run vs. delete modes.
### License
The script and this documentation are released under the Simplified BSD License (see header in `cleanSnaps`).