'\" t
.TH "CLONETAB" "5" "" "systemd 262" "clonetab"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
clonetab \- Configuration for dm\-clone block devices
.SH "SYNOPSIS"
.PP
/etc/clonetab
.SH "DESCRIPTION"
.PP
The
/etc/clonetab
file describes dm\-clone block devices that are set up during system boot\&.
.PP
Empty lines and lines starting with the
"#"
character are ignored\&. Each of the remaining lines describes one dm\-clone device\&. Fields are delimited by white space\&.
.PP
Each line is in the form
.sp
.if n \{\
.RS 4
.\}
.nf
\fIname\fR \fIsource\-device\fR \fIdestination\-device\fR \fImetadata\-device\fR [\fIoptions\fR]
.fi
.if n \{\
.RE
.\}
.sp
The first four fields are mandatory, the fifth is optional\&.
.PP
The five fields of
/etc/clonetab
are defined as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  1." 4.2
.\}
The first field contains the name of the resulting dm\-clone device; its block device is set up below
/dev/mapper/\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  2." 4.2
.\}
The second field contains a path to the read\-only source block device\&. This is the device whose data is cloned to the destination device\&. Reads to regions not yet hydrated are served directly from this device\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  3." 4.2
.\}
The third field contains a path to the writable destination block device\&. The source device\*(Aqs data is copied here in the background\&. It must be at least as large as the source device\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  4." 4.2
.\}
The fourth field contains a path to the metadata block device\&. This small device tracks which regions of the destination have been hydrated and is managed exclusively by dm\-clone\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP "  5." 4.2
.\}
The fifth field, if present, contains comma\-separated
"key=value"
options\&. The following option is supported:
.PP
\fBregion\-size=\fR\fB\fIBYTES\fR\fR
.RS 4
Controls the granularity of background hydration copying \(em how much data is copied at a time\&. Region size is specified in bytes (standard suffixes like
"K",
"M",
"G"
are supported), and 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\&.
.sp
One region is the atomic unit dm\-clone tracks: it is either fully hydrated (copied to the destination) or not, never partially\&. If a copy is interrupted mid\-region, that whole region is retried from scratch on next boot\&. Smaller regions mean finer progress tracking; larger regions reduce metadata overhead\&. Defaults to
"4K"\&. For background, see
\m[blue]\fBdm\-clone kernel documentation\fR\m[]\&\s-2\u[1]\d\s+2\&.
.sp
Added in version 262\&.
.RE
.sp
If no options are needed, the field may be omitted entirely or
"\-"
may be used as a placeholder\&.
.RE
.PP
At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by
\fBsystemd-clonesetup-generator\fR(8)\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Simple clone without options\fR
.PP
Clone a source device to a destination, using a separate metadata device:
.sp
.if n \{\
.RS 4
.\}
.nf
mydevice /dev/sdb /dev/sdc /dev/sdd
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&2.\ \&Clone with custom region size\fR
.PP
Clone a source device to a destination with a custom region size of 8 KiB:
.sp
.if n \{\
.RS 4
.\}
.nf
mydevice /dev/sdb /dev/sdc /dev/sdd region\-size=8K
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\fBsystemd\fR(1), \fBsystemd-clonesetup-generator\fR(8), \fBdmsetup\fR(8)
.SH "NOTES"
.IP " 1." 4
dm-clone kernel documentation
.RS 4
\%https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/dm-clone.html
.RE