man/integritytab.xml

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