CLONETAB(5)

💖 clonetab — like, the config file for dm-clone block devices (this is the clonetab(5) manual, bestie)

okay so welcome to the glow-up guide for /etc/clonetab ✨ this is section 5 of the manual, and it's all about setting up your dm-clone block devices. no cap.

---

🌸 SYNOPSIS 🌸

/etc/clonetab

that's it. that's the whole synopsis. she's lowkey simple like that 💅

---

🦋 DESCRIPTION 🦋

so /etc/clonetab is the file that describes all your dm-clone block devices that get set up when the system boots. it's giving "boot-time plans" fr fr.

• Empty lines? ignored. ghosted. 💀
• Lines that start with the # character? also ignored. comments get a pass, periodt.
• Every other line describes exactly one dm-clone device.
• Fields are delimited by white space. (spaces, tabs, whatever, she's flexible)

Each line is in this form:

name source-device destination-device metadata-device [options]

the first four fields are mandatory (no skipping, bestie), and the fifth is optional. 🫶

the five fields of /etc/clonetab are defined as follows, one by one, no gatekeeping:

1. the first field — this is the name of the resulting dm-clone device. its block device gets set up down below in /dev/mapper/. she lives there now. 👑
2. the second field — a path to the read-only source block device. this is the device whose data is getting cloned over to the destination device. reads to regions that aren't hydrated yet are served directly from this device. so she's the original, the blueprint, the main character. ✨
3. the third field — a path to the writable destination block device. the source device's data gets copied here in the background (like, quietly, while you're living your life). it must be at least as large as the source device — no shrinking, that's not the vibe. ⚠️
4. the fourth field — a path to the metadata block device. this little guy is small but so important: it tracks which regions of the destination have been hydrated, and it's managed exclusively by dm-clone. like, do not touch. it's taken. 🙈
5. the fifth field — if it's present, it holds comma-separated key=value options. here's the one option that's supported:
   • region-size=BYTES — this controls the granularity of background hydration copying, aka how much data gets copied at a time. the region size is specified in bytes (and yes, standard suffixes like K, M, G are supported, slay), and it must correspond to a power of two between 4 KiB and 1 GiB. for example, region-size=4K or region-size=4096 sets a 4 KiB region size. 📏

one region is the atomic unit dm-clone tracks — the way that it's either fully hydrated (copied to the destination) or not, never partially. if a copy gets interrupted mid-region, that whole entire region is retried from scratch on the next boot. brutal but honest. 💀

smaller regions mean finer progress tracking; larger regions reduce metadata overhead. it's a tradeoff, iykyk.

it defaults to 4K. for background info, go read the dm-clone kernel documentation (linked in NOTES below, bestie).

Added in version 262.

if no options are needed at all, you can just omit the field entirely, or use - as a placeholder. either one, she doesn't mind. 🎀

at early boot, and also whenever the system manager configuration gets reloaded, this file gets translated into native systemd units by systemd-clonesetup-generator(8). so like, the generator does the heavy lifting. 💪

---

🌈 EXAMPLES 🌈

Example 1. Simple clone without options

clone a source device to a destination, using a separate metadata device:

mydevice /dev/sdb /dev/sdc /dev/sdd

clean, minimal, no notes. she ate. 🍓

Example 2. Clone with custom region size

clone a source device to a destination with a custom region size of 8 KiB:

mydevice /dev/sdb /dev/sdc /dev/sdd region-size=8K

now that's a vibe check passed with flying colours. ⭐

---

👑 SEE ALSO 👑

• systemd(1)
• systemd-clonesetup-generator(8)
• dmsetup(8)

---

🧚 NOTES 🧚

1. dm-clone kernel documentation — literally the lore, the source material, the receipts: https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/dm-clone.html

---

ok so quick reminder bestie: that destination device has to be at least as large as the source, and the metadata device is exclusively dm-clone's. respect the boundaries. 🫶

---

and that's the whole page, no crumbs left 💜 this came to you from systemd 262.1 — mwah, love her, iconic, periodt. ✨🎀💅