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.

### 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>] [--help|-h] [pool]
```

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

### Behavior

- By default, 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. Use `--force` to perform destruction via `zfs destroy`.
- 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

- Run with a 30-day forward time-shift (simulate time 30 days later):

```
cleanSnaps -t 30d
cleanSnaps -t 2592000   # equivalent (30 days in seconds)
```

- Actually remove all snapshots found from pool tank, displaying each step while doing so:

```
cleanSnaps -f -v tank
```

- Restrict processing to pool `tank` (only snapshots whose pool prefix matches `tank` will be considered):

```
cleanSnaps tank
```

- Feed the script a list of snapshots on stdin (for testing):

```
cat sample-snapshots.txt | cleanSnaps -t 3600
```

### 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.
- 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 script depends on standard Perl modules available in most Perl 5 installations. See the script header for exact module imports.

### 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. Use that test to validate behavior before running against real ZFS pools.

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