What are the requirements for naming a ZFS snapshot?

Hi,

I run Core TrueNAS-13.0-U6.2 and live in Europe, hence recently switched from Central European Summer Time (CEST) to Central European Time (CET).

CEST ended at 2024-10-27T03:00:00+0200 where CET started at 2024-10-27T02:00:00+0100.

For the sake of clarity, I name my ZFS snapshops similarly to the ISO-8601 notation.

After a replication task following the end of CEST, I received this alert:

New alerts:
* Replication "local -> remote3" failed: warning: cannot send 'tank3/home@auto-
frequent-20241027T021500:0200': not an earlier snapshot from the same fs
Replication cannot continue because existing snapshot auto-
hourly-20241027T020000:0100 is newer than tank3/home@auto-
frequent-20241027T021500:0200, but has an older date in the snapshot name. To
resolve the error, rename tank3/home@auto-frequent-20241027T021500:0200 with a
date that is older than auto-hourly-20241027T020000:0100 or delete snapshot
tank3/home@auto-frequent-20241027T021500:0200 from both the source and
destination. cannot receive: failed to read from stream..

Snapshot auto-hourly-20241027T020000:0100 is indeed newer than tank3/home@auto- frequent-20241027T021500:0200, about 45 minutes newer.

I found that the first part of the alert message comes from openzfs (see occurrences of not an earlier snapshot from the same fs within zfs/lib/libzfs/libzfs_sendrecv.c at master · openzfs/zfs · GitHub).

However, for:

but has an older date in the snapshot name.

I cannot find where this comes from, it this TrueNAS or vanilla openzfs? Is this documented somewhere?

How relevant is the naming of the snapshots? Can’t we name them the way we want?

Thank you greatly for your help!

The snapshot’s name is used by (TrueNAS’s) zettarepl. Rather than use metadata (slower), it parses through the snapshot names (faster). That’s why it’s important to include the date and time information in the name itself.

Yes you can, and there is no limitation from vanilla OpenZFS (except for certain characters). But with TrueNAS, there’s a reason why a standardized (date-time) naming convention is used. (See above.)

2 Likes

What is the convention exactly?

In my TrueNAS Periodic Snapshot Task, I have a Naming Schema field that I can personalize. The default is documented as:

The default is auto-{0}-{1}-{2}_{3}-{4}.

Does the default constitute the convention?

Is that a typo in their tooltips? :sweat_smile:

The default is actually %Y-%m-%d_%H-%M
(year-month-day_hour-minute)
(2024-11-03_10-00)

{0}-{1}-{2}_{3}-{4} looks like a placeholder when they were writing up the tooltips, and forgot to change it to the correct variables.


At minimum, you need to specify a year, month, and day-of-month, so that zettarepl can safely prune “old” snapshots, without ambiguity.

That means at minimum this: %Y-%m-%d

However, you’ll also want to include more granular time (such as hour and minute), especially if the task frequency (and pruning schedule) necessitates it. (You don’t want a pruning schedule for “older than 6 hours” if the snapshot names don’t even include the hour.)


The only way around the shift in daylight savings is to include additional information in the “name”. Just know that it will only “solve” the problem for exactly two days of the entire year.

More precisely, zettarepl requirement is to have date and time, but you can arrange this information pretty much any way you want.
My naming scheme is auto_%Y%m%d_%H%M. I use the same for daily, weekly and monthly snapshots, and the single snapshot taken at midnight automagically ends up being retained for two weeks, two months or five years, as fit. Zettarepl is rather smart, but daylight saving time is a nuisance.

2 Likes

Yes, there is clearly a lack of clarity in the documentation :laughing:

What is your recommendation to name snapshots?

That honestly looks like a bug they missed. :eyes:


Other than the issue with daylight savings, what’s wrong with the default?

Other than the issue with daylight savings, I don’t think there is anything wrong.

But that is the thing, having my TrueNAS server in Europe and specifying the System > General > Timezone accordingly, even if I use the default snapshot naming, then I supposed I am bound to have problem at the end of Daylight Saving Time since the snapshot name will use the local time, right?

1 Like

Correct. That’s why you have to ask yourself “Is it worth it to add more information to a snapshot’s name, in its task, just to avoid this conflict twice a year?”

For some, it might be. I guess you could add a variable at the end that specifies the current timezone. (For example, PST vs PDT.) I think it’s possible with the %Z or %z variable. (Not sure if the former variable’s outputted name will change in European timezones, like it does in the US?)

But if you do this now, it will affect the snapshots that were already created, since their naming schema now differs from the new snapshots. (They will not be pruned.)

Well, the Naming Schema of my Periodic Snapshot Tasks are as followed:

  • auto-frequent-%Y%m%dT%H%M%S%z
  • auto-hourly-%Y%m%dT%H%M%S%z
  • auto-daily-%Y%m%dT%H%M%S%z

and I am having the problem that I just started to understand thanks to you.

I recall that I changed the Naming Schema precisely because of the problem with DST and replication.

The way I see it now is that the only solution is, sadly, to set my server timezone as UTC. I do not see any possibility to avoid the problem otherwise.

How do you deal with this issue yourself?

I don’t. I just accept that two days in the year, some snapshots will be skipped.

In my case, this is not acceptable unfortunately.

I started reading zettarepl’s documentation and I see:

Common replication parameters

…

# Specifies timezone which is used for snapshot creation date and time
# Defaults to system timezone
timezone: "US/Pacific"

That would be far better that changing the system timezone.

However, I do not see a way to configure zettarepl within TrueNAS. Is is even possible?

You don’t, directly. It runs in the backend.

You configure, in the GUI, the different tasks that use it. (Periodic Snapshots, Replications, etc).

Add the %z or %Z datetime variables to the snapshot’s naming schema. But there is a caveat.

So use UTC and enjoy not dealing with the transitions between summer and winter time.

Nowadays, computers are perfectly capable to deal with daylight savings so that we, humans, can enjoy dealing with local times.

I understand that there are no ways to configure zettarepl which is surprising for a tool that I believe to be targeted at power users. Also surprising is the fact that TrueNAS does not document that it uses zettarepl.

Your suggestion is probably the best (least worst) solution as I see it now but it is less than satisfactory.

Generally I prefer to use unix timestamps in lieu of ISO-8601 strings for snapshots (if I need that in the name for some reason) for sake of brevity. I doubt anyone has written a time-related tool that can’t parse a unix timestamp.

It’s better to keep snapshot names relatively short since these count toward the overall 255 character limit for ZFS dataset names. Though admittedly, it’s better than in FreeBSD 11 and earlier where we faced an 88 character limit for name of mounted filesystems and going overboard with snapshot name could cause it to fail to mount. :slight_smile:

1 Like

That is an interesting approach which would solve my problem without having to set my server in UTC.
However, I would have difficult time to make sense of the timestamp while looking at a snapshot name. So it is not human-friendly either, but at least it is contained to snapshot names.

Not to sound like a pest, but keep this in mind if you’re going to change the snapshot naming scheme after-the-fact:

You could possibly just let these old (pre-name change) snapshots remain, and then months or years later manually bulk delete them, since zettarepl will no longer prune them (due to the name change)

1 Like