ZPOOL-ATTACH(8)

💖 ZPOOL-ATTACH 💖

okay so bestie, welcome to zpool-attach — that's the zpool-attach(8) page from the System Manager's Manual, and it's literally the glow-up button for your vdevs. let's get into it 🫶

---

✨ NAME ✨

zpool-attach — attach new device to existing ZFS vdev

no cap, that's the whole name. iconic.

---

🌸 SYNOPSIS 🌸

zpool attach [-fsw] [-o property=value] pool vdev new_device

that's the whole vibe. pool, then the vdev you already have, then the new_device you're introducing to the group chat.

---

🦋 DESCRIPTION 🦋

So you're attaching new_device to the existing vdev. cute! but the way it behaves depends on what kind of vdev you're attaching to — RAID-Z or mirror/plain. two totally different storylines, bestie.

🎀 when the vdev is a mirror or a plain device

If your existing vdev is a mirror or plain device (think: specified as "sda" or "mirror-7"), then the new device gets mirrored with the existing vdev, a resilver kicks off, and once that resilver completes the new device starts contributing to additional redundancy. slay.

• If vdev is not currently part of a mirrored configuration, the device automatically transforms into a two-way mirror of device and new_device.
• If vdev is part of a two-way mirror, attaching new_device creates a three-way mirror, and so on.

In either case, new_device begins to resilver immediately and any running scrub is canceled. (yes, canceled. it's giving "we have bigger things going on" 💅)

🌈 when the vdev is a RAID-Z device

If the existing vdev is a RAID-Z device (like, specified as "raidz2-0"), then the new device becomes part of that RAID-Z group. A "raidz expansion" gets initiated, and once the expansion completes, the new device contributes additional space to the RAID-Z group. ✨

The expansion entails reading all allocated space from existing disks in the RAID-Z group, and rewriting it to the new disks in the RAID-Z group (including the newly added device). you can watch its progress with zpool status — very main character, go check on it.

Data redundancy is maintained during and after the expansion. If a disk fails while the expansion is in progress, the expansion pauses until the health of the RAID-Z vdev is restored (e.g. by replacing the failed disk and waiting for reconstruction to complete). it just waits. patiently. 🧚

Expansion does not change the number of failures that can be tolerated without data loss (e.g. a RAID-Z2 is still a RAID-Z2 even after expansion). and yes, a RAID-Z vdev can be expanded multiple times. obsessed.

After the expansion completes, old blocks retain their old data-to-parity ratio (e.g. 5-wide RAID-Z2 has 3 data and 2 parity) but distributed among the larger set of disks. New blocks will be written with the new data-to-parity ratio (e.g. a 5-wide RAID-Z2 which has been expanded once to 6-wide, has 4 data and 2 parity). However — and this is the plot twist — the vdev's assumed parity ratio does not change, so slightly less space than is expected may be reported for newly-written blocks, according to zfs list, df, ls -s, and similar tools. not a bug bestie, just math being math 😭

A pool-wide scrub is initiated at the end of the expansion in order to verify the checksums of all blocks which have been copied during the expansion. a little farewell gift, we love that for us.

---

👑 the flags 👑

• -f — Forces use of new_device, even if it appears to be in use. but heads up: not all vdevs can be overridden in this manner.
• -o property=value — Sets the given pool properties. See the zpoolprops(7) manual page for a list of valid properties that can be set. The only property supported at the moment is ashift.
• -s — When attaching to a mirror or plain vdev, the new_device is reconstructed sequentially to restore redundancy as quickly as possible. Checksums are not verified during sequential reconstruction, so a scrub is started when the resilver completes. (trade-off queen 💅)
• -w — Waits until new_device has finished resilvering or expanding before returning. it will simply not let you leave. clingy in a supportive way.

---

💜 SEE ALSO 💜

• zpool-add(8)
• zpool-detach(8)
• zpool-import(8)
• zpool-initialize(8)
• zpool-online(8)
• zpool-replace(8)
• zpool-resilver(8)

go read those too, they're the rest of the friend group fr fr 🌸

---

and that's the page!! brought to you by OpenZFS, dated November 8, 2023 — this whole ZPOOL-ATTACH(8) moment was served to you fresh from the System Manager's Manual. now go attach something and be the redundancy your pool deserves 💖✨🎀🦋👑