mirror of
https://github.com/systemd/systemd
synced 2024-11-05 18:25:39 +00:00
326 lines
15 KiB
XML
326 lines
15 KiB
XML
<?xml version="1.0"?>
|
|
<!--*-nxml-*-->
|
|
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/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> <optional><replaceable>options</replaceable></optional></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
|
|
<varname>UUID=</varname> followed by the <replaceable>UUID</replaceable>.</para>
|
|
|
|
<para>The third field contains a path to the underlying block hash device, or a specification of a block device via
|
|
<varname>UUID=</varname> followed by the <replaceable>UUID</replaceable>.</para>
|
|
|
|
<para>The fourth field is the <replaceable>roothash</replaceable> 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>superblock=<replaceable>BOOL</replaceable></option></term>
|
|
|
|
<listitem><para>Use dm-verity with or without permanent on-disk superblock.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>format=<replaceable>NUMBER</replaceable></option></term>
|
|
|
|
<listitem><para>Specifies the hash version type. Format type <literal>0</literal> is original Chrome OS version. Format type <literal>1</literal> is
|
|
modern version.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>data-block-size=<replaceable>BYTES</replaceable></option></term>
|
|
|
|
<listitem><para>Used block size for the data device. (Note kernel supports only page-size as maximum
|
|
here; Multiples of 512 bytes.) </para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>hash-block-size=<replaceable>BYTES</replaceable></option></term>
|
|
|
|
<listitem><para>Used block size for the hash device. (Note kernel supports only page-size as maximum
|
|
here; Multiples of 512 bytes.)</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>data-blocks=<replaceable>BLOCKS</replaceable></option></term>
|
|
|
|
<listitem><para>Number of blocks of data device used in verification. If not specified, the whole device is
|
|
used.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>hash-offset=<replaceable>BYTES</replaceable></option></term>
|
|
|
|
<listitem><para>Offset of hash area/superblock on <literal>hash-device</literal>. (Multiples of 512 bytes.)
|
|
</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>salt=<replaceable>HEX</replaceable></option></term>
|
|
|
|
<listitem><para>Salt used for format or verification. Format is a hexadecimal string; 256 bytes long maximum;
|
|
<literal>-</literal> is the special value for empty.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>uuid=<replaceable>UUID</replaceable></option></term>
|
|
|
|
<listitem><para>Use the provided <replaceable>UUID</replaceable> instead of generating new one. The <replaceable>UUID</replaceable> must be
|
|
provided in standard <acronym>UUID</acronym> format, e.g. <literal>12345678-1234-1234-1234-123456789abc</literal>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<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 <acronym>IO</acronym> operation with <acronym>I/O</acronym> error. With <option>--ignore-corruption</option> option the
|
|
corruption is only logged. With <option>--restart-on-corruption</option> or
|
|
<option>--panic-on-corruption</option> the kernel is restarted (panicked) immediately.
|
|
|
|
(You have to provide way how to avoid restart loops.)</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v248"/></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.</para>
|
|
|
|
<warning>
|
|
<para>Use this option only in very specific cases. This option is available since Linux kernel version 4.5.</para>
|
|
</warning>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v248"/></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.</para>
|
|
|
|
<warning>
|
|
<para>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>
|
|
</warning>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>hash=<replaceable>HASH</replaceable></option></term>
|
|
|
|
<listitem><para>Hash algorithm for dm-verity. This should be the name of the algorithm, like "sha1". For default
|
|
see <command>veritysetup --help</command>.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>fec-device=<replaceable>PATH</replaceable></option></term>
|
|
|
|
<listitem><para>Use forward error correction (<acronym>FEC</acronym>) to recover from corruption if hash verification fails. Use
|
|
encoding data from the specified device. The fec device argument can be block device or file image.
|
|
If fec device path doesn't exist, it will be created as file. Note: block sizes for data and hash devices must
|
|
match. Also, if the verity data_device is encrypted the fec_device should be too.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>fec-offset=<replaceable>BYTES</replaceable></option></term>
|
|
|
|
<listitem><para>This is the offset, in bytes, from the start of the <acronym>FEC</acronym> device to the beginning of the encoding
|
|
data. (Aligned on 512 bytes.)</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>fec-roots=<replaceable>NUM</replaceable></option></term>
|
|
|
|
<listitem><para>Number of generator roots. This equals to the number of parity bytes in the encoding data. In
|
|
RS(M, N) encoding, the number of roots is M-N. M is 255 and M-N is between 2 and 24 (including).</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v254"/>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>root-hash-signature=<replaceable>PATH</replaceable>|base64:<replaceable>HEX</replaceable></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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v248"/></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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v248"/>
|
|
</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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v248"/></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>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v248"/></listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term><option>x-initrd.attach</option></term>
|
|
|
|
<listitem><para>Setup this verity protected block device in the initrd, 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 initrd should
|
|
use this option.</para>
|
|
|
|
<xi:include href="version-info.xml" xpointer="v248"/>
|
|
</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><simplelist type="inline">
|
|
<member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-veritysetup@.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
|
<member><citerefentry><refentrytitle>systemd-veritysetup-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
|
<member><citerefentry project='man-pages'><refentrytitle>fstab</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
|
|
<member><citerefentry project='die-net'><refentrytitle>veritysetup</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
|
|
</simplelist></para>
|
|
</refsect1>
|
|
|
|
</refentry>
|