]>
Commit | Line | Data |
---|---|---|
1f1a2243 TA |
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, | |
fe003f02 | 53 | <literal>PARTLABEL=</literal> followed by the partition label. |
1f1a2243 TA |
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 | ||
bcc1ee56 | 75 | <varlistentry> |
a2160ba0 | 76 | <term><option>mode=(journal|bitmap|direct)</option></term> |
bcc1ee56 RH |
77 | |
78 | <listitem><para> | |
a2160ba0 AK |
79 | Enable journaled, bitmapped or direct (passthrough) mode. Journaled mode is the default when this option is not specified. |
80 | It provides safety against crashes, but can be slow because all data has to be written twice. | |
81 | Bitmap mode is more efficient since it requires only a single write, but it is less reliable because if data corruption happens when the machine crashes, it may not be detected. | |
82 | Direct mode disables the journal and the bitmap. Corresponds to the "direct writes" mode documented in | |
bcc1ee56 RH |
83 | <ulink url="https://docs.kernel.org/admin-guide/device-mapper/dm-integrity.html">the dm-integrity documentation</ulink>. |
84 | Note that without a journal, if there is a crash, it is possible that the integrity tags and data will not match. If used, the journal-* | |
85 | options below will have no effect if passed. | |
86 | </para></listitem> | |
87 | </varlistentry> | |
88 | ||
1f1a2243 TA |
89 | <varlistentry> |
90 | <term><option>journal-watermark=[0..100]%</option></term> | |
91 | ||
92 | <listitem><para> | |
93 | Journal watermark in percent. When the journal percentage exceeds this watermark, the journal flush will be started. Setting a value of | |
94 | "0%" uses default value. | |
95 | </para></listitem> | |
96 | </varlistentry> | |
97 | ||
98 | <varlistentry> | |
99 | <term><option>journal-commit-time=[0..N]</option></term> | |
100 | ||
101 | <listitem><para> | |
102 | Commit time in milliseconds. When this time passes (and no explicit flush operation was issued), the journal is written. Setting a value of | |
103 | zero uses default value. | |
104 | </para></listitem> | |
105 | </varlistentry> | |
106 | ||
107 | <varlistentry> | |
108 | <term><option>data-device=/dev/disk/by-...</option></term> | |
109 | ||
110 | <listitem><para> | |
111 | Specify a separate block device that contains existing data. The second field specified in the | |
112 | integritytab for block device then will contain calculated integrity tags and journal for data-device, | |
113 | but not the end user data. | |
114 | </para></listitem> | |
115 | </varlistentry> | |
116 | ||
117 | <varlistentry> | |
118 | <term><option>integrity-algorithm=[crc32c|crc32|sha1|sha256|hmac-sha256]</option></term> | |
119 | ||
120 | <listitem><para> | |
121 | The algorithm used for integrity checking. The default is crc32c. Must match option used during format. | |
122 | </para></listitem> | |
123 | </varlistentry> | |
124 | </variablelist> | |
125 | ||
126 | <para>At early boot and when the system manager configuration is | |
127 | reloaded, this file is translated into native systemd units by | |
128 | <citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> | |
129 | </refsect1> | |
130 | ||
131 | <refsect1> | |
132 | <title>Examples</title> | |
133 | <example> | |
134 | <title>/etc/integritytab</title> | |
135 | <para>Set up two integrity protected block devices. </para> | |
136 | ||
137 | <programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 - journal-commit-time=10,allow-discards,journal-watermark=55% | |
138 | data PARTUUID=5d4b1808-be76-774d-88af-03c4c3a41761 - allow-discards | |
139 | </programlisting> | |
140 | </example> | |
141 | ||
142 | <example> | |
143 | <title>/etc/integritytab</title> | |
144 | <para>Set up 1 integrity protected block device using defaults </para> | |
145 | ||
146 | <programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8</programlisting> | |
147 | </example> | |
148 | ||
149 | <example> | |
150 | <title>/etc/integritytab</title> | |
151 | <para>Set up 1 integrity device using existing data block device which contains user data </para> | |
152 | ||
153 | <programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 - data-device=/dev/disk/by-uuid/9276d9c0-d4e3-4297-b4ff-3307cd0d092f</programlisting> | |
154 | </example> | |
155 | ||
156 | <example> | |
157 | <title>/etc/integritytab</title> | |
158 | <para>Set up 1 integrity device using a HMAC key file using defaults </para> | |
159 | ||
160 | <programlisting>home PARTUUID=4973d0b8-1b15-c449-96ec-94bab7f6a7b8 /etc/hmac.key</programlisting> | |
161 | </example> | |
162 | ||
163 | </refsect1> | |
164 | ||
165 | <refsect1> | |
166 | <title>See Also</title> | |
167 | <para> | |
168 | <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, | |
169 | <citerefentry><refentrytitle>systemd-integritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
170 | <citerefentry><refentrytitle>systemd-integritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
171 | <citerefentry project='die-net'><refentrytitle>integritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, | |
172 | </para> | |
173 | </refsect1> | |
174 | ||
175 | </refentry> |