Honeydew - 2.7.0

Jonathan Vasquez (fearedbliss)

Description

A simple snapshot cleaner for OpenZFS written in Zig.

License

Released under the Simplified BSD License.

Build

1. Download and Install Zig 0.16.0.
2. Run zig build -Doptimize=ReleaseSafe.
3. You can find the binary at zig-out/bin/honeydew.

Usage

To start using the application, all you need to do is run:

./honeydew -p <pool name> -d <cutoff date>

A cutoff date must be provided. The application currently doesn't support defaulting to a 30 day range since there is no OS clock integration yet. You can check out the small script below which can help with automating the date generation string.

You can use many of the options documented below to modify the behavior (Including the ability to list snapshots that should be excluded (and thus protected) from deletion). For more information, you can run: ./honeydew -h for a detailed list of parameters as well.

For example, if we wanted to clean a pool called tank, use an exclude file called excluded_snapshots that contains a list of snapshots to exclude (one per line), we want to show what snapshots will be removed, and what snapshots are excluded, and we want to set an arbitrary date in the future that will make all of our snapshots old (and thus you are basically saying: delete all the snapshots except the ones I've excluded), you can do so as follows:

./honeydew -p tank -e excluded_snapshots -s -x -d 2099-01-01-0000-00

If you wanted to only remove snapshots that have a particular tag, you can use the -l option. For example, the following command will also only delete snapshots that have the ANIMALS tag:

./honeydew -p tank -e excluded_snapshots -s -x -d 2099-01-01-0000-00 -l ANIMALS

Format

For simplicity, there is only one snapshot format accepted, which is in the following format:

YYYY-mm-dd-HHMM-ss-LABEL => 2020-05-01-2345-15-CHECKPOINT

The following command will yield a correctly formatted date (BSD/GNU date):

date +%F-%H%M-%S

You can then concatenate the label.

Example:

#!/bin/sh

POOL="tank"
DATE="$(date +%F-%H%M-%S)"
TAG="ANIMALS"
SNAPSHOT_NAME="${DATE}-${TAG}"

zfs snapshot "${POOL}@${SNAPSHOT_NAME}"

The above should yield a snapshot similar to the following:

tank@2020-08-23-1023-17-ANIMALS

The snapshot cleaner will silently skip any snapshots that don't follow this naming convention exactly. This allows you to maintain your own out-of-band snapshots (like using poudriere snapshots, or snapshots with your own naming scheme) without being annoyed by the app. There is no time validation for the digits, meaning that if you put in 61 seconds, that will still be valid. If you have snapshots with characters after the fact, like the example below, they will be ignored.

tank@2020-08-23-1023-17-ANIMALS-BUT-WAIT-THERE-IS-MORE

Options

Usage:
    honeydew -p <pool> -d <cutoff date> ...

Required:
   -p, --pool <pool>                 The pool you want to clean.
   -d, --date <date>                 The cutoff date you want to use for snapshot deletions.

Options:
    -c, --show-config                Displays the full configuration options used by the application.
    -x, --show-excluded              Show snapshots that will be excluded.
    -s, --show-queued                Show snapshots that will be deleted.
    -e, --exclude-file <file>        Snapshots that should be excluded from deletion.
    -l, --label <label>              Only snapshots with this label will be considered for deletion.
    -i, --per-iteration <count>      Number of snapshots to delete per iteration.
    -f, --no-confirm                 Deletes snapshots without confirmation. Used primarily for automations.
    -n, --dry-run                    Performs a dry run. No deletions will occur.
    -h, --help                       Prints help information.
    -V, --version                    Prints version information.

Dependencies

• ZFS must be installed on your system and available in your PATH.
• Your user must have permission to delete snapshots.

Contributions

Before opening a PR, please make sure the code is properly formatted, and all tests are passing. You can do this by running the following commands:

• zig fmt src/*
• zig test src/tests.zig