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>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>