ZFS-RENAME(8)

💖 zfs-rename — bestie, we're renaming a ZFS dataset 💖

okay so this is the zfs-rename page from the System Manager's Manual — it's the part of the zfs command family that handles renaming ZFS datasets. sit down, hydrate, let's go ✨

---

🌸 SYNOPSIS 🌸

zfs rename [-f] filesystem|volume|snapshot filesystem|volume|snapshot
zfs rename -p [-f] filesystem|volume filesystem|volume
zfs rename -u [-f] filesystem filesystem
zfs rename -r snapshot snapshot

like, four whole shapes of the same command. pick your fighter 💅

---

🦋 DESCRIPTION 🦋

zfs rename [-f] filesystem|volume|snapshot filesystem|volume|snapshot

zfs rename -p [-f] filesystem|volume filesystem|volume

zfs rename -u [-f] filesystem filesystem

so basically: this renames the dataset you give it. the new target can live anywhere in the ZFS hierarchy — with one big exception, and the exception is snapshots. snapshots can only be renamed within their parent file system or volume. and when you're renaming a snapshot, you don't have to spell out the parent file system as part of the second argument. also, renamed file systems can inherit new mount points, and if that happens they get unmounted and remounted at the new mount point. it's giving glow-up, honestly ✨

• -f — force unmount any file systems that need to be unmounted during this whole process. ⚠️ heads up though: this flag has no effect if you use it together with the -u flag. they don't vibe together, fr fr.
• -p — creates all the nonexistent parent datasets for you. datasets created this way get automatically mounted according to the mountpoint property they inherit from their parent. so cute, it just builds the whole family tree 🫶
• -u — do not remount file systems during rename. and lowkey a lil bonus fact: if a file system's mountpoint property is set to legacy or none, the file system is not unmounted even if this option is not given. so it's already chillin'. 😌

---

zfs rename -r snapshot snapshot

🎀 the recursive one 🎀

this recursively renames the snapshots of all descendent datasets. and ngl — snapshots are the only dataset that can be renamed recursively. that's the whole rule, no exceptions, periodt. 👑

---

✨ EXAMPLES ✨

💅 Example 1: Promoting a ZFS Clone

so here's the lil routine: you test out changes to a file system, and then replace the original file system with the changed one, using clones, clone promotion, and renaming. the commands below illustrate exactly how:

# zfs create pool/project/production
  populate /pool/project/production with data
# zfs snapshot pool/project/production@today
# zfs clone pool/project/production@today pool/project/beta
  make changes to /pool/project/beta and test them
# zfs promote pool/project/beta
# zfs rename pool/project/production pool/project/legacy
# zfs rename pool/project/beta pool/project/production
  once the legacy version is no longer needed, it can be destroyed
# zfs destroy pool/project/legacy

the beta becomes the production, the production becomes the legacy, the legacy gets destroyed. it's giving succession arc 🌈 the main character really did that.

---

🧚 Example 2: Performing a Rolling Snapshot

this one shows how to keep a history of snapshots with a consistent naming scheme. to keep a week's worth of snapshots, the user destroys the oldest snapshot, renames the remaining snapshots, and then creates a new snapshot, like so:

# zfs destroy -r pool/users@7daysago
# zfs rename -r pool/users@6daysago @7daysago
# zfs rename -r pool/users@5daysago @6daysago
# zfs rename -r pool/users@4daysago @5daysago
# zfs rename -r pool/users@3daysago @4daysago
# zfs rename -r pool/users@2daysago @3daysago
# zfs rename -r pool/users@yesterday @2daysago
# zfs rename -r pool/users@today @yesterday
# zfs snapshot -r pool/users@today

everyone shuffles down one slot, the oldest leaves the group chat, and a fresh @today joins at the top. rotating the roster, slay 💖

also notice: in the snapshot renames here, the parent file system doesn't need to be repeated in the second argument — that's the rule from DESCRIPTION doing its thing. iykyk.

---

and that's the whole page bestie!! this one's from OpenZFS, dated July 11, 2022, and it lives in section 8 of the manual. go forth and rename responsibly, mwah 🫶✨💅