Skip to content

Commit db54386

Browse files
src-upsrc-up
committed
clonesetup: add support to clone devices via /etc/clonetab
Adds dm-clone device setup at boot via a new /etc/clonetab config file, following the crypttab/veritytab pattern. - Add systemd-clonesetup-generator to parse /etc/clonetab and generate units. - Add systemd-clonesetup binary to create/remove dm-clone devices via ioctl. - Add clonesetup.target for ordering dm-clone activation at boot. - Add region_size= option in clonetab to configure dm-clone hydration granularity. - Add clonetab(5) and systemd-clonesetup-generator(8) man pages. Fixes: systemd#39500
1 parent 67f72f1 commit db54386

18 files changed

Lines changed: 1405 additions & 0 deletions

‎docs/ENVIRONMENT.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -76,6 +76,10 @@ All tools:
7676
`/etc/veritytab`. Only useful for debugging. Currently only supported by
7777
`systemd-veritysetup-generator`.
7878

79+
* `$SYSTEMD_CLONETAB` — if set, use this path instead of
80+
`/etc/clonetab`. Only useful for debugging. Currently only supported by
81+
`systemd-clonesetup-generator`.
82+
7983
* `$SYSTEMD_DEFAULT_HOSTNAME` — override the compiled-in fallback hostname
8084
(relevant in particular for the system manager and `systemd-hostnamed`).
8185
Must be a valid hostname (either a single label or a FQDN).

‎man/clonetab.xml‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
<?xml version="1.0"?>
2+
<!--*-nxml-*-->
3+
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4+
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
5+
<!--
6+
SPDX-License-Identifier: LGPL-2.1-or-later
7+
-->
8+
<refentry id="clonetab" xmlns:xi="http://www.w3.org/2001/XInclude">
9+
10+
<refentryinfo>
11+
<title>clonetab</title>
12+
<productname>systemd</productname>
13+
</refentryinfo>
14+
15+
<refmeta>
16+
<refentrytitle>clonetab</refentrytitle>
17+
<manvolnum>5</manvolnum>
18+
</refmeta>
19+
20+
<refnamediv>
21+
<refname>clonetab</refname>
22+
<refpurpose>Configuration for dm-clone block devices</refpurpose>
23+
</refnamediv>
24+
25+
<refsynopsisdiv>
26+
<para><filename>/etc/clonetab</filename></para>
27+
</refsynopsisdiv>
28+
29+
<refsect1>
30+
<title>Description</title>
31+
32+
<para>The <filename>/etc/clonetab</filename> file describes
33+
dm-clone block devices that are set up during system boot.</para>
34+
35+
<para>Empty lines and lines starting with the <literal>#</literal>
36+
character are ignored. Each of the remaining lines describes one
37+
dm-clone device. Fields are delimited by white space.</para>
38+
39+
<para>Each line is in the form<programlisting><replaceable>name</replaceable> <replaceable>source-device</replaceable> <replaceable>destination-device</replaceable> <replaceable>metadata-device</replaceable> [<replaceable>options</replaceable>]</programlisting>
40+
The first four fields are mandatory, the fifth is optional.</para>
41+
42+
<para>The five fields of <filename>/etc/clonetab</filename> are defined as follows:</para>
43+
44+
<orderedlist>
45+
46+
<listitem><para>The first field contains the name of the resulting dm-clone device; its
47+
block device is set up below <filename>/dev/mapper/</filename>.</para></listitem>
48+
49+
<listitem><para>The second field contains a path to the read-only source block device.
50+
This is the device whose data is cloned to the destination device. Reads to regions not
51+
yet hydrated are served directly from this device.</para></listitem>
52+
53+
<listitem><para>The third field contains a path to the writable destination block device.
54+
The source device's data is copied here in the background. It must be at least as
55+
large as the source device.</para></listitem>
56+
57+
<listitem><para>The fourth field contains a path to the metadata block device. This
58+
small device tracks which regions of the destination have been hydrated and is managed
59+
exclusively by dm-clone.</para></listitem>
60+
61+
<listitem><para>The fifth field, if present, contains comma-separated <literal>key=value</literal>
62+
options. The following option is supported:</para>
63+
64+
<variablelist>
65+
<varlistentry>
66+
<term><option>region_size=<replaceable>BYTES</replaceable></option></term>
67+
<listitem><para>Controls the granularity of background hydration copying — how much
68+
data is copied at a time. Region size is specified in bytes (standard suffixes like
69+
<literal>K</literal>, <literal>M</literal>, <literal>G</literal> are supported), and must
70+
correspond to a power of two between 4 KiB and 1 GiB. For example,
71+
<literal>region_size=4K</literal> or <literal>region_size=4096</literal> sets a 4 KiB region size.</para>
72+
73+
<para>
74+
One region is the atomic unit dm-clone tracks: it is either fully hydrated (copied to the destination)
75+
or not, never partially. If a copy is interrupted mid-region, that whole region is
76+
retried from scratch on next boot. Smaller regions mean finer progress tracking;
77+
larger regions reduce metadata overhead. Defaults to <literal>4K</literal>. For background, see
78+
<ulink url="https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/dm-clone.html">dm-clone kernel documentation</ulink>.
79+
</para>
80+
81+
<xi:include href="version-info.xml" xpointer="v262"/></listitem>
82+
</varlistentry>
83+
</variablelist>
84+
85+
<para>If no options are needed, the field may be omitted entirely or
86+
<literal>-</literal> may be used as a placeholder.</para>
87+
</listitem>
88+
89+
</orderedlist>
90+
91+
<para>At early boot and when the system manager configuration is reloaded, this file is
92+
translated into native systemd units by
93+
<citerefentry><refentrytitle>systemd-clonesetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
94+
</refsect1>
95+
96+
<refsect1>
97+
<title>Examples</title>
98+
99+
<example>
100+
<title>Simple clone without options</title>
101+
<para>Clone a source device to a destination, using a separate metadata device:</para>
102+
<programlisting>mydevice /dev/sdb /dev/sdc /dev/sdd</programlisting>
103+
</example>
104+
105+
<example>
106+
<title>Clone with custom region size</title>
107+
<para>Clone a source device to a destination with a custom region size of 8 KiB:</para>
108+
<programlisting>mydevice /dev/sdb /dev/sdc /dev/sdd region_size=8K</programlisting>
109+
</example>
110+
</refsect1>
111+
112+
<refsect1>
113+
<title>See Also</title>
114+
<para><simplelist type="inline">
115+
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
116+
<member><citerefentry><refentrytitle>systemd-clonesetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
117+
<member><citerefentry project='die-net'><refentrytitle>dmsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
118+
</simplelist></para>
119+
</refsect1>
120+
121+
</refentry>

‎man/rules/meson.build‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ manpages = [
1515
['bootup', '7', [], ''],
1616
['busctl', '1', [], ''],
1717
['capsule@.service', '5', [], ''],
18+
['clonetab', '5', [], ''],
1819
['coredump.conf', '5', ['coredump.conf.d'], 'ENABLE_COREDUMP'],
1920
['coredumpctl', '1', [], 'ENABLE_COREDUMP'],
2021
['crypttab', '5', [], 'HAVE_LIBCRYPTSETUP'],
@@ -1024,6 +1025,11 @@ manpages = [
10241025
['systemd-cat', '1', [], ''],
10251026
['systemd-cgls', '1', [], ''],
10261027
['systemd-cgtop', '1', [], ''],
1028+
['systemd-clonesetup',
1029+
'8',
1030+
['systemd-clonesetup@.service'],
1031+
''],
1032+
['systemd-clonesetup-generator', '8', [], ''],
10271033
['systemd-coredump',
10281034
'8',
10291035
['systemd-coredump.socket', 'systemd-coredump@.service'],

‎man/systemd-clonesetup-generator.xml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
<?xml version="1.0"?>
2+
<!--*-nxml-*-->
3+
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4+
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
5+
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6+
<refentry id="systemd-clonesetup-generator" xmlns:xi="http://www.w3.org/2001/XInclude">
7+
8+
<refentryinfo>
9+
<title>systemd-clonesetup-generator</title>
10+
<productname>systemd</productname>
11+
</refentryinfo>
12+
13+
<refmeta>
14+
<refentrytitle>systemd-clonesetup-generator</refentrytitle>
15+
<manvolnum>8</manvolnum>
16+
</refmeta>
17+
18+
<refnamediv>
19+
<refname>systemd-clonesetup-generator</refname>
20+
<refpurpose>Unit generator for <filename>/etc/clonetab</filename></refpurpose>
21+
</refnamediv>
22+
23+
<refsynopsisdiv>
24+
<para><filename>/usr/lib/systemd/system-generators/systemd-clonesetup-generator</filename></para>
25+
</refsynopsisdiv>
26+
27+
<refsect1>
28+
<title>Description</title>
29+
30+
<para><filename>systemd-clonesetup-generator</filename> is a generator that translates
31+
<filename>/etc/clonetab</filename> into native systemd units early at boot and when
32+
configuration of the system manager is reloaded. This will create
33+
<citerefentry><refentrytitle>systemd-clonesetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
34+
units as necessary.</para>
35+
36+
<para><filename>systemd-clonesetup-generator</filename> implements
37+
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
38+
</refsect1>
39+
40+
<refsect1>
41+
<title>See Also</title>
42+
<para><simplelist type="inline">
43+
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
44+
<member><citerefentry><refentrytitle>clonetab</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
45+
<member><citerefentry><refentrytitle>systemd-clonesetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
46+
<member><citerefentry project='die-net'><refentrytitle>dmsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
47+
</simplelist></para>
48+
</refsect1>
49+
50+
</refentry>

‎man/systemd-clonesetup.xml‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
<?xml version="1.0"?>
2+
<!--*-nxml-*-->
3+
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
4+
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
5+
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6+
<refentry id="systemd-clonesetup" xmlns:xi="http://www.w3.org/2001/XInclude">
7+
8+
<refentryinfo>
9+
<title>systemd-clonesetup</title>
10+
<productname>systemd</productname>
11+
</refentryinfo>
12+
13+
<refmeta>
14+
<refentrytitle>systemd-clonesetup</refentrytitle>
15+
<manvolnum>8</manvolnum>
16+
</refmeta>
17+
18+
<refnamediv>
19+
<refname>systemd-clonesetup</refname>
20+
<refname>systemd-clonesetup@.service</refname>
21+
<refpurpose>Set up and tear down dm-clone devices</refpurpose>
22+
</refnamediv>
23+
24+
<refsynopsisdiv>
25+
<cmdsynopsis>
26+
<command>systemd-clonesetup</command>
27+
<arg choice="plain">add</arg>
28+
<arg choice="plain">NAME</arg>
29+
<arg choice="plain">SOURCE-DEVICE</arg>
30+
<arg choice="plain">DEST-DEVICE</arg>
31+
<arg choice="plain">META-DEVICE</arg>
32+
<arg choice="opt">OPTIONS</arg>
33+
</cmdsynopsis>
34+
35+
<cmdsynopsis>
36+
<command>systemd-clonesetup</command>
37+
<arg choice="plain">remove</arg>
38+
<arg choice="plain">NAME</arg>
39+
</cmdsynopsis>
40+
41+
<para><filename>systemd-clonesetup@.service</filename></para>
42+
</refsynopsisdiv>
43+
44+
<refsect1>
45+
<title>Description</title>
46+
47+
<para><command>systemd-clonesetup</command> is used to set up (with <command>add</command>) and tear down
48+
(with <command>remove</command>) dm-clone devices. It is primarily used via
49+
<filename>systemd-clonesetup@.service</filename> units generated from
50+
<filename>/etc/clonetab</filename> by
51+
<citerefentry><refentrytitle>systemd-clonesetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
52+
</para>
53+
54+
<para>The positional arguments <parameter>NAME</parameter>, <parameter>SOURCE-DEVICE</parameter>,
55+
<parameter>DEST-DEVICE</parameter>, <parameter>META-DEVICE</parameter>, and <parameter>OPTIONS</parameter>
56+
have the same meaning as the fields in
57+
<citerefentry><refentrytitle>clonetab</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
58+
59+
<para>Currently, the supported option in <parameter>OPTIONS</parameter> is
60+
<varname>region_size=</varname><replaceable>BYTES</replaceable>, where
61+
<replaceable>BYTES</replaceable> is measured in bytes (standard suffixes like
62+
<literal>K</literal>, <literal>M</literal>, <literal>G</literal> are supported).</para>
63+
</refsect1>
64+
65+
<refsect1>
66+
<title>See Also</title>
67+
<para><simplelist type="inline">
68+
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
69+
<member><citerefentry><refentrytitle>clonetab</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
70+
<member><citerefentry><refentrytitle>systemd-clonesetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
71+
<member><citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
72+
<member><citerefentry project='die-net'><refentrytitle>dmsetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
73+
</simplelist></para>
74+
</refsect1>
75+
76+
</refentry>

‎meson.build‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -302,6 +302,7 @@ conf.set_quoted('SYSTEMD_USERWORK_PATH', libexecdir / 'syst
302302
conf.set_quoted('SYSTEMD_MOUNTWORK_PATH', libexecdir / 'systemd-mountwork')
303303
conf.set_quoted('SYSTEMD_NSRESOURCEWORK_PATH', libexecdir / 'systemd-nsresourcework')
304304
conf.set_quoted('SYSTEMD_VERITYSETUP_PATH', libexecdir / 'systemd-veritysetup')
305+
conf.set_quoted('SYSTEMD_CLONESETUP_PATH', libexecdir / 'systemd-clonesetup')
305306
conf.set_quoted('SYSTEM_CONFIG_UNIT_DIR', pkgsysconfdir / 'system')
306307
conf.set_quoted('SYSTEM_DATA_UNIT_DIR', systemunitdir)
307308
conf.set_quoted('SYSTEM_ENV_GENERATOR_DIR', systemenvgeneratordir)
@@ -2129,6 +2130,7 @@ subdir('src/bootctl')
21292130
subdir('src/busctl')
21302131
subdir('src/cgls')
21312132
subdir('src/cgtop')
2133+
subdir('src/clonesetup')
21322134
subdir('src/coredump')
21332135
subdir('src/creds')
21342136
subdir('src/cryptenroll')

0 commit comments

Comments
 (0)