| <?xml version="1.0"?> |
| <!--*-nxml-*--> |
| <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> |
| <!-- |
| SPDX-License-Identifier: LGPL-2.1-or-later |
| |
| This is based on crypttab(5). |
| |
| --> |
| <refentry id="veritytab" conditional='HAVE_LIBCRYPTSETUP' xmlns:xi="http://www.w3.org/2001/XInclude"> |
| |
| <refentryinfo> |
| <title>veritytab</title> |
| <productname>systemd</productname> |
| </refentryinfo> |
| |
| <refmeta> |
| <refentrytitle>veritytab</refentrytitle> |
| <manvolnum>5</manvolnum> |
| </refmeta> |
| |
| <refnamediv> |
| <refname>veritytab</refname> |
| <refpurpose>Configuration for verity block devices</refpurpose> |
| </refnamediv> |
| |
| <refsynopsisdiv> |
| <para><filename>/etc/veritytab</filename></para> |
| </refsynopsisdiv> |
| |
| <refsect1> |
| <title>Description</title> |
| |
| <para>The <filename>/etc/veritytab</filename> file describes |
| verity protected block devices that are set up during |
| system boot.</para> |
| |
| <para>Empty lines and lines starting with the <literal>#</literal> |
| character are ignored. Each of the remaining lines describes one |
| verity protected block device. Fields are delimited by |
| white space.</para> |
| |
| <para>Each line is in the form<programlisting><replaceable>volume-name</replaceable> <replaceable>data-device</replaceable> <replaceable>hash-device</replaceable> <replaceable>roothash</replaceable> <replaceable>options</replaceable></programlisting> |
| The first four fields are mandatory, the remaining one is optional.</para> |
| |
| <para>The first field contains the name of the resulting verity volume; its block device is set up |
| below <filename>/dev/mapper/</filename>.</para> |
| |
| <para>The second field contains a path to the underlying block data device, or a specification of a block device via |
| <literal>UUID=</literal> followed by the UUID.</para> |
| |
| <para>The third field contains a path to the underlying block hash device, or a specification of a block device via |
| <literal>UUID=</literal> followed by the UUID.</para> |
| |
| <para>The fourth field is the <literal>roothash</literal> in hexadecimal.</para> |
| |
| <para>The fifth field, if present, is a comma-delimited list of options. The following options are |
| recognized:</para> |
| |
| <variablelist class='fstab-options'> |
| |
| <varlistentry> |
| <term><option>ignore-corruption</option></term> |
| <term><option>restart-on-corruption</option></term> |
| <term><option>panic-on-corruption</option></term> |
| |
| <listitem><para>Defines what to do if a data verity problem is detected (data corruption). Without these |
| options kernel fails the IO operation with I/O error. With <literal>--ignore-corruption</literal> option the |
| corruption is only logged. With <literal>--restart-on-corruption</literal> or |
| <literal>--panic-on-corruption</literal> the kernel is restarted (panicked) immediately. |
| |
| (You have to provide way how to avoid restart loops.)</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>ignore-zero-blocks</option></term> |
| |
| <listitem><para>Instruct kernel to not verify blocks that are expected to contain zeroes and always directly |
| return zeroes instead. |
| |
| WARNING: Use this option only in very specific cases. This option is available since Linux kernel version 4.5. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>check-at-most-once</option></term> |
| |
| <listitem><para>Instruct kernel to verify blocks only the first time they are read from the data device, rather |
| than every time. |
| |
| WARNING: It provides a reduced level of security because only offline tampering of the data device's content |
| will be detected, not online tampering. This option is available since Linux kernel version 4.17. |
| </para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>root-hash-signature=</option></term> |
| |
| <listitem><para>A base64 string encoding the root hash signature prefixed by <literal>base64:</literal> or a |
| path to roothash signature file used to verify the root hash (in kernel). This feature requires Linux kernel |
| version 5.4 or more recent.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>_netdev</option></term> |
| |
| <listitem><para>Marks this veritysetup device as requiring network. It will be |
| started after the network is available, similarly to |
| <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| units marked with <option>_netdev</option>. The service unit to set up this device |
| will be ordered between <filename>remote-fs-pre.target</filename> and |
| <filename>remote-veritysetup.target</filename>, instead of |
| <filename>veritysetup-pre.target</filename> and |
| <filename>veritysetup.target</filename>.</para> |
| |
| <para>Hint: if this device is used for a mount point that is specified in |
| <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| the <option>_netdev</option> option should also be used for the mount |
| point. Otherwise, a dependency loop might be created where the mount point |
| will be pulled in by <filename>local-fs.target</filename>, while the |
| service to configure the network is usually only started <emphasis>after</emphasis> |
| the local file system has been mounted.</para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>noauto</option></term> |
| |
| <listitem><para>This device will not be added to <filename>veritysetup.target</filename>. |
| This means that it will not be automatically enabled on boot, unless something else pulls |
| it in. In particular, if the device is used for a mount point, it'll be enabled |
| automatically during boot, unless the mount point itself is also disabled with |
| <option>noauto</option>.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>nofail</option></term> |
| |
| <listitem><para>This device will not be a hard dependency of |
| <filename>veritysetup.target</filename>. It'll still be pulled in and started, but the system |
| will not wait for the device to show up and be enabled, and boot will not fail if this is |
| unsuccessful. Note that other units that depend on the enabled device may still fail. In |
| particular, if the device is used for a mount point, the mount point itself also needs to |
| have the <option>nofail</option> option, or the boot will fail if the device is not enabled |
| successfully.</para></listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term><option>x-initrd.attach</option></term> |
| |
| <listitem><para>Setup this verity protected block device in the initramfs, similarly to |
| <citerefentry><refentrytitle>systemd.mount</refentrytitle><manvolnum>5</manvolnum></citerefentry> |
| units marked with <option>x-initrd.mount</option>.</para> |
| |
| <para>Although it's not necessary to mark the mount entry for the root file system with |
| <option>x-initrd.mount</option>, <option>x-initrd.attach</option> is still recommended with |
| the verity protected block device containing the root file system as otherwise systemd |
| will attempt to detach the device during the regular system shutdown while it's still in |
| use. With this option the device will still be detached but later after the root file |
| system is unmounted.</para> |
| |
| <para>All other verity protected block devices that contain file systems mounted in the |
| initramfs should use this option.</para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| |
| <para>At early boot and when the system manager configuration is |
| reloaded, this file is translated into native systemd units by |
| <citerefentry><refentrytitle>systemd-veritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para> |
| </refsect1> |
| |
| <refsect1> |
| <title>Examples</title> |
| <example> |
| <title>/etc/veritytab example</title> |
| <para>Set up two verity protected block devices. One using device blocks, another using files.</para> |
| |
| <programlisting>usr PARTUUID=783e45ae-7aa3-484a-beef-a80ff9c19cbb PARTUUID=21dc1dfe-4c33-8b48-98a9-918a22eb3e37 36e3f740ad502e2c25e2a23d9c7c17bf0fdad2300b7580842d4b7ec1fb0fa263 auto |
| data /etc/data /etc/hash a5ee4b42f70ae1f46a08a7c92c2e0a20672ad2f514792730f5d49d7606ab8fdf auto |
| </programlisting> |
| </example> |
| </refsect1> |
| |
| <refsect1> |
| <title>See Also</title> |
| <para> |
| <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-veritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry><refentrytitle>systemd-veritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| <citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry>, |
| <citerefentry project='die-net'><refentrytitle>veritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry>, |
| </para> |
| </refsect1> |
| |
| </refentry> |