Skip to content

Commit eaaa02b

Browse files
poetteringpoettering
authored
Merge pull request systemd#20902 from tasleson/integritysetup-generator
Add stand-alone dm integrity support
2 parents 2aa94bb + 1f1a224 commit eaaa02b

22 files changed

+848
-20
lines changed

‎docs/ENVIRONMENT.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,10 @@ All tools:
5050
useful for debugging. Currently only supported by
5151
`systemd-cryptsetup-generator`.
5252

53+
* `$SYSTEMD_INTEGRITYTAB` — if set, use this path instead of
54+
`/etc/integritytab`. Only useful for debugging. Currently only supported by
55+
`systemd-integritysetup-generator`.
56+
5357
* `$SYSTEMD_VERITYTAB` — if set, use this path instead of
5458
`/etc/veritytab`. Only useful for debugging. Currently only supported by
5559
`systemd-veritysetup-generator`.

‎man/integritytab.xml‎

Lines changed: 161 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
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.2/docbookx.dtd">
5+
<!--
6+
SPDX-License-Identifier: LGPL-2.1-or-later
7+
8+
-->
9+
<refentry id="integritytab" conditional='HAVE_LIBCRYPTSETUP' xmlns:xi="http://www.w3.org/2001/XInclude">
10+
11+
<refentryinfo>
12+
<title>integritytab</title>
13+
<productname>systemd</productname>
14+
</refentryinfo>
15+
16+
<refmeta>
17+
<refentrytitle>integritytab</refentrytitle>
18+
<manvolnum>5</manvolnum>
19+
</refmeta>
20+
21+
<refnamediv>
22+
<refname>integritytab</refname>
23+
<refpurpose>Configuration for integrity block devices</refpurpose>
24+
</refnamediv>
25+
26+
<refsynopsisdiv>
27+
<para><filename>/etc/integritytab</filename></para>
28+
</refsynopsisdiv>
29+
30+
<refsect1>
31+
<title>Description</title>
32+
33+
<para>The <filename>/etc/integritytab</filename> file describes
34+
integrity protected block devices that are set up during
35+
system boot.</para>
36+
37+
<para>Empty lines and lines starting with the <literal>#</literal>
38+
character are ignored. Each of the remaining lines describes one
39+
verity integrity protected block device. Fields are delimited by
40+
white space.</para>
41+
42+
<para>Each line is in the form<programlisting><replaceable>volume-name</replaceable> <replaceable>block-device</replaceable>
43+
<replaceable>[keyfile|-]</replaceable> <replaceable>[options|-]</replaceable></programlisting>
44+
The first two fields are mandatory, the remaining two are optional and only required if user specified non-default options during integrity format.</para>
45+
46+
<para>The first field contains the name of the resulting integrity volume; its block device is set up
47+
below <filename>/dev/mapper/</filename>.</para>
48+
49+
<para>The second field contains a path to the underlying block device, or a specification of a block device via
50+
<literal>UUID=</literal> followed by the UUID,
51+
<literal>PARTUUID=</literal> followed by the partition UUID,
52+
<literal>LABEL=</literal> followed by the label,
53+
<literal>PARTLABEL=</literal> followed by the partition label,
54+
</para>
55+
56+
<para>The third field if present contains an absolute filename path to a key file or a <literal>-</literal>
57+
to specify none. When the filename is present, the "integrity-algorithm" defaults to <literal>hmac-sha256</literal>
58+
with the key length derived from the number of bytes in the key file. At this time the only supported integrity algorithm
59+
when using key file is hmac-sha256. The maximum size of the key file is 4096 bytes.
60+
</para>
61+
62+
<para>The fourth field, if present, is a comma-delimited list of options or a <literal>-</literal> to specify none. The following options are
63+
recognized:</para>
64+
<variablelist>
65+
66+
<varlistentry>
67+
<term><option>allow-discards</option></term>
68+
69+
<listitem><para>
70+
Allow the use of discard (TRIM) requests for the device.
71+
This option is available since the Linux kernel version 5.7.
72+
</para></listitem>
73+
</varlistentry>
74+
75+
<varlistentry>
76+
<term><option>journal-watermark=[0..100]%</option></term>
77+
78+
<listitem><para>
79+
Journal watermark in percent. When the journal percentage exceeds this watermark, the journal flush will be started. Setting a value of
80+
"0%" uses default value.
81+
</para></listitem>
82+
</varlistentry>
83+
84+
<varlistentry>
85+
<term><option>journal-commit-time=[0..N]</option></term>
86+
87+
<listitem><para>
88+
Commit time in milliseconds. When this time passes (and no explicit flush operation was issued), the journal is written. Setting a value of
89+
zero uses default value.
90+
</para></listitem>
91+
</varlistentry>
92+
93+
<varlistentry>
94+
<term><option>data-device=/dev/disk/by-...</option></term>
95+
96+
<listitem><para>
97+
Specify a separate block device that contains existing data. The second field specified in the
98+
integritytab for block device then will contain calculated integrity tags and journal for data-device,
99+
but not the end user data.
100+
</para></listitem>
101+
</varlistentry>
102+
103+
<varlistentry>
104+
<term><option>integrity-algorithm=[crc32c|crc32|sha1|sha256|hmac-sha256]</option></term>
105+
106+
<listitem><para>
107+
The algorithm used for integrity checking. The default is crc32c. Must match option used during format.
108+
</para></listitem>
109+
</varlistentry>
110+
</variablelist>
111+
112+
<para>At early boot and when the system manager configuration is
113+
reloaded, this file is translated into native systemd units by
114+
<citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
115+
</refsect1>
116+
117+
<refsect1>
118+
<title>Examples</title>
119+
<example>
120+
<title>/etc/integritytab</title>
121+
<para>Set up two integrity protected block devices. </para>
122+
123+
<programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 - journal-commit-time=10,allow-discards,journal-watermark=55%
124+
data PARTUUID=5d4b1808-be76-774d-88af-03c4c3a41761 - allow-discards
125+
</programlisting>
126+
</example>
127+
128+
<example>
129+
<title>/etc/integritytab</title>
130+
<para>Set up 1 integrity protected block device using defaults </para>
131+
132+
<programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8</programlisting>
133+
</example>
134+
135+
<example>
136+
<title>/etc/integritytab</title>
137+
<para>Set up 1 integrity device using existing data block device which contains user data </para>
138+
139+
<programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 - data-device=/dev/disk/by-uuid/9276d9c0-d4e3-4297-b4ff-3307cd0d092f</programlisting>
140+
</example>
141+
142+
<example>
143+
<title>/etc/integritytab</title>
144+
<para>Set up 1 integrity device using a HMAC key file using defaults </para>
145+
146+
<programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 /etc/hmac.key</programlisting>
147+
</example>
148+
149+
</refsect1>
150+
151+
<refsect1>
152+
<title>See Also</title>
153+
<para>
154+
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
155+
<citerefentry><refentrytitle>systemd-integritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
156+
<citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
157+
<citerefentry project='die-net'><refentrytitle>integritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
158+
</para>
159+
</refsect1>
160+
161+
</refentry>

‎man/rules/meson.build‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -24,6 +24,7 @@ manpages = [
2424
['hostname', '5', [], ''],
2525
['hostnamectl', '1', [], 'ENABLE_HOSTNAMED'],
2626
['hwdb', '7', [], 'ENABLE_HWDB'],
27+
['integritytab', '5', [], 'HAVE_LIBCRYPTSETUP'],
2728
['journal-remote.conf', '5', ['journal-remote.conf.d'], 'HAVE_MICROHTTPD'],
2829
['journal-upload.conf', '5', ['journal-upload.conf.d'], 'HAVE_MICROHTTPD'],
2930
['journalctl', '1', [], ''],
@@ -882,6 +883,11 @@ manpages = [
882883
'8',
883884
['systemd-initctl', 'systemd-initctl.socket'],
884885
'HAVE_SYSV_COMPAT'],
886+
['systemd-integritysetup-generator', '8', [], 'HAVE_LIBCRYPTSETUP'],
887+
['systemd-integritysetup@.service',
888+
'8',
889+
['systemd-integritysetup'],
890+
'HAVE_LIBCRYPTSETUP'],
885891
['systemd-journal-gatewayd.service',
886892
'8',
887893
['systemd-journal-gatewayd', 'systemd-journal-gatewayd.socket'],

‎man/systemd-integritysetup-generator.xml‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
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.2/docbookx.dtd">
5+
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6+
<refentry id="systemd-integritysetup-generator" conditional='HAVE_LIBCRYPTSETUP'>
7+
8+
<refentryinfo>
9+
<title>systemd-integritysetup-generator</title>
10+
<productname>systemd</productname>
11+
</refentryinfo>
12+
13+
<refmeta>
14+
<refentrytitle>systemd-integritysetup-generator</refentrytitle>
15+
<manvolnum>8</manvolnum>
16+
</refmeta>
17+
18+
<refnamediv>
19+
<refname>systemd-integritysetup-generator</refname>
20+
<refpurpose>Unit generator for integrity protected block devices</refpurpose>
21+
</refnamediv>
22+
23+
<refsynopsisdiv>
24+
<para><filename>/usr/lib/systemd/system-generators/systemd-integritysetup-generator</filename></para>
25+
</refsynopsisdiv>
26+
27+
<refsect1>
28+
<title>Description</title>
29+
30+
<para><filename>systemd-integritysetup-generator</filename> is a generator that translates <filename>/etc/integritytab</filename> entries into
31+
native systemd units early at boot. This will create
32+
<citerefentry><refentrytitle>systemd-integritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
33+
units as necessary.</para>
34+
35+
<para><command>systemd-integritysetup-generator</command> implements
36+
<citerefentry><refentrytitle>systemd.generator</refentrytitle><manvolnum>7</manvolnum></citerefentry>.</para>
37+
</refsect1>
38+
39+
<refsect1>
40+
<title>See Also</title>
41+
<para>
42+
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
43+
<citerefentry><refentrytitle>systemd-integritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
44+
<citerefentry project='die-net'><refentrytitle>integritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
45+
</para>
46+
</refsect1>
47+
48+
</refentry>

‎man/systemd-integritysetup@.service.xml‎

Lines changed: 95 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,95 @@
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.2/docbookx.dtd">
5+
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
6+
<refentry id="systemd-integritysetup@.service" conditional='HAVE_LIBCRYPTSETUP'>
7+
8+
<refentryinfo>
9+
<title>systemd-integritysetup@.service</title>
10+
<productname>systemd</productname>
11+
</refentryinfo>
12+
13+
<refmeta>
14+
<refentrytitle>systemd-integritysetup@.service</refentrytitle>
15+
<manvolnum>8</manvolnum>
16+
</refmeta>
17+
18+
<refnamediv>
19+
<refname>systemd-integritysetup@.service</refname>
20+
<refname>systemd-integritysetup</refname>
21+
<refpurpose>Disk integrity protection logic</refpurpose>
22+
</refnamediv>
23+
24+
<refsynopsisdiv>
25+
<para><filename>systemd-integritysetup@.service</filename></para>
26+
<para><filename>/usr/lib/systemd/systemd-integritysetup</filename></para>
27+
</refsynopsisdiv>
28+
29+
<refsect1>
30+
<title>Description</title>
31+
32+
<para><filename>systemd-integritysetup@.service</filename> is a service responsible for setting up integrity
33+
protected block devices. It should be instantiated for each device that requires integrity
34+
protection.</para>
35+
36+
<para>At early boot and when the system manager configuration is reloaded, entries from /etc/integritytab are converted into
37+
<filename>systemd-integritysetup@.service</filename> units by
38+
<citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
39+
40+
<para><filename>systemd-integritysetup@.service</filename> calls <command>systemd-integritysetup</command>.</para>
41+
</refsect1>
42+
43+
<refsect1>
44+
<title>Commands</title>
45+
46+
<para>The following commands are understood by <command>systemd-integritysetup</command>:</para>
47+
48+
<variablelist>
49+
<varlistentry>
50+
<term>
51+
<option>attach</option>
52+
<replaceable>volume</replaceable>
53+
<replaceable>device</replaceable>
54+
[<replaceable>key-file|-</replaceable>]
55+
[<replaceable>option(s)|-</replaceable>]
56+
</term>
57+
58+
<listitem><para>Create a block device <replaceable>volume</replaceable> using
59+
<replaceable>device</replaceable>. See integritytab man page and
60+
<ulink url="https://www.kernel.org/doc/html/latest/admin-guide/device-mapper/dm-integrity.html">
61+
Kernel dm-integrity</ulink> documentation for details.
62+
</para></listitem>
63+
</varlistentry>
64+
65+
<varlistentry>
66+
<term>
67+
<option>detach</option>
68+
<replaceable>volume</replaceable>
69+
</term>
70+
71+
<listitem><para>Detach (destroy) the block device
72+
<replaceable>volume</replaceable>.</para></listitem>
73+
</varlistentry>
74+
75+
<varlistentry>
76+
<term>
77+
<option>help</option>
78+
</term>
79+
80+
<listitem><para>Print short information about command syntax.</para></listitem>
81+
</varlistentry>
82+
</variablelist>
83+
</refsect1>
84+
85+
<refsect1>
86+
<title>See Also</title>
87+
<para>
88+
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
89+
<citerefentry><refentrytitle>integritytab</refentrytitle><manvolnum>5</manvolnum></citerefentry>,
90+
<citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
91+
<citerefentry project='die-net'><refentrytitle>integritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>
92+
</para>
93+
</refsect1>
94+
95+
</refentry>

‎man/systemd-veritysetup-generator.xml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717

1818
<refnamediv>
1919
<refname>systemd-veritysetup-generator</refname>
20-
<refpurpose>Unit generator for integrity protected block devices</refpurpose>
20+
<refpurpose>Unit generator for verity protected block devices</refpurpose>
2121
</refnamediv>
2222

2323
<refsynopsisdiv>
@@ -28,7 +28,7 @@
2828
<title>Description</title>
2929

3030
<para><filename>systemd-veritysetup-generator</filename> is a generator that translates kernel command line options
31-
configuring integrity-protected block devices (verity) into native systemd units early at boot and when
31+
configuring verity protected block devices into native systemd units early at boot and when
3232
configuration of the system manager is reloaded. This will create
3333
<citerefentry><refentrytitle>systemd-veritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
3434
units as necessary.</para>
@@ -66,7 +66,7 @@
6666
data devices to use are automatically derived from the specified hash value. Specifically, the data partition
6767
device is looked for under a GPT partition UUID derived from the first 128bit of the root hash, the hash
6868
partition device is looked for under a GPT partition UUID derived from the last 128bit of the root hash. Hence
69-
it is usually sufficient to specify the root hash to boot from an integrity protected root file system, as
69+
it is usually sufficient to specify the root hash to boot from a verity protected root file system, as
7070
device paths are automatically determined from it — as long as the partition table is properly set up.</para>
7171
</listitem>
7272
</varlistentry>
@@ -76,7 +76,7 @@
7676
<term><varname>systemd.verity_root_hash=</varname></term>
7777

7878
<listitem><para>These two settings take block device paths as arguments and may be used to explicitly
79-
configure the data partition and hash partition to use for setting up the integrity protection for the root file
79+
configure the data partition and hash partition to use for setting up the verity protection for the root file
8080
system. If not specified, these paths are automatically derived from the <varname>roothash=</varname> argument
8181
(see above).</para></listitem>
8282
</varlistentry>

‎man/systemd-veritysetup@.service.xml‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@
1818
<refnamediv>
1919
<refname>systemd-veritysetup@.service</refname>
2020
<refname>systemd-veritysetup</refname>
21-
<refpurpose>Disk integrity protection logic</refpurpose>
21+
<refpurpose>Disk verity protection logic</refpurpose>
2222
</refnamediv>
2323

2424
<refsynopsisdiv>
@@ -29,12 +29,12 @@
2929
<refsect1>
3030
<title>Description</title>
3131

32-
<para><filename>systemd-veritysetup@.service</filename> is a service responsible for setting up integrity
33-
protection (verity) block devices. It should be instantiated for each device that requires integrity
32+
<para><filename>systemd-veritysetup@.service</filename> is a service responsible for setting up verity
33+
protection block devices. It should be instantiated for each device that requires verity
3434
protection.</para>
3535

3636
<para>At early boot and when the system manager configuration is reloaded kernel command line configuration for
37-
integrity protected block devices is translated into <filename>systemd-veritysetup@.service</filename> units by
37+
verity protected block devices is translated into <filename>systemd-veritysetup@.service</filename> units by
3838
<citerefentry><refentrytitle>systemd-veritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para>
3939

4040
<para><filename>systemd-veritysetup@.service</filename> calls <command>systemd-veritysetup</command>.</para>

0 commit comments

Comments
 (0)