Subversion Repositories zfs_utils

## 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`).