Skip to content

Draft: add support for integritysetup (dm-integrity) devices

Melvin Vermeeren requested to merge vermeeren/cryptsetup:initramfs-integritysetup into debian/latest

Hi,

This MR adds /etc/integritytab support for activation of integritysetup (dm-integrity) devices during boot, supporting all options via generic mechanism. dm-integrity uses checksum to prevent disk device from returining bad data which can cause data corruption even in RAID array. https://gitlab.com/cryptsetup/cryptsetup/-/wikis/DMIntegrity

Notes:

  • This is a version I use in production on a few hosts so far and I believe is ready for upstreaming.
    • As far as I know, no other distro with support or generic script exist in the wild yet. Most things I found use hardcoded scripts which is of course a bad thing.
    • In addition to the above, udev style auto opening cannot work, as arguments have to be passed to integritysetup in similar fashion to cryptsetup.
  • Integritysetup is always on lowest block device layer it must be below raid to work properly.

The documentation is currently not added in XML format, instead refer to the below which is inside /etc/integritytab in my current deployments. I can of course convert this to XML for native man page instead. My intention is to collaborate, polish this up and get it released into Debian, because is the completely new feature I would like some feedback and thoughts on this first before doing more work on this.

Task list:

  • Handle all TODO in the patches themselves.
    • These are things I am not certain about or things that need path changes before official inclusion.
  • Convert documentation to manpage/xml format for integritytab(5).
  • Integrate systemd service with Debian packaging logic.
# Syntax: <name> <dev> [<options>]
# Update initramfs after changing! update-initramfs -u -k all
#
# Suggested block device stack for typical encrypted RAID configuration:
# 	partition -> integritysetup -> mdadm -> cryptsetup -> lvm -> filesystem
#
# Options are comma separated and may not contain any whitespace.
# 	option1,option2=value,option3,...
# Options map directly to integritysetup long options:
# 	integritytab         || integritysetup cli
# 	---------------------||-----------------------
# 	integrity=crc32c     || --integrity crc32c
# 	data-device=/dev/foo || --data-device /dev/foo
# 	allow-discards       || --allow-discards
# 	integrity-no-journal || --integrity-no-journal
# 	anyopt               || --anyopt
# 	anyopt=example       || --anyopt example
#
# The following built-in aliases exist for consistency with crypttab:
# 	integritytab         || integritysetup cli
# 	---------------------||-----------------------
# 	discard              || --allow-discards
#
# It is strongly recommended you always set the "integrity" option.
# As of writing (2021-04-20) integritysetup superblock does not contain the
# integrity algorithm in use. If a future version changes the default it will
# cause major issues, most likely every read resulting in I/O error due to
# checksum mismatch. The algorithm in use can be viewed with "dmsetup table".
#
# Like with crypttab(5), the <dev> can be specified in various ways.
# Note that the "data-device" option also supports all of these.
# 	Device path:     /dev/path
# 	Label:           LABEL=<label>
# 	UUID:            UUID=<uuid>
# 	Partition UUID:  PARTUUID=<partuuid>
# 	Partition label: PARTLABEL=<partlabel>
# Because an integrity device lacks a UUID and labels are not considered
# reliable enough it is strongly recommended to always use partition UUID for
# the raw disk partition containing the data or data and metadata.
#
# Examples:
# 	# Root is on a fast SSD supporting TRIM (discard).
#	is_root PARTUUID=123abc integrity=crc32c,discard
#
#	# Media is on a slow HDD.
#	is_media PARTUUID=456def integrity=crc32c
#
#	# The below puts integrity metadata on fast SSD for performance and puts
#	# the actual data on a slow HDD, resulting in optimal performance.
#	#
#	# The metadata on the SSD here should be redundant via RAID.
#	# Typically stored in an LVM LV in the suggested device stack above.
#	is_hdd /dev/ssd-vg/is_hdd_meta integrity=crc32c,data-device=PARTUUID=hdd
#
# IMPORTANT: When using "data-device" option the data device itself does not
# contain the integrity superblock, which means that it appears on the system as
# a completely plain device exposing what is inside it. mdadm's auto array start
# feature using UUIDs can and will open the data device directly when it gets
# the chance, bypassing the integrity layer. In order to prevent this from
# happening it is crucial to explicitly set the "DEVICE" option in mdadm.conf(5)
# so the devices are manually specified, which also disables automatic scanning.
# Example with explicit listing:
# 	DEVICE /dev/mapper/is_hdd_0
# 	DEVICE /dev/mapper/is_hdd_1
# If you consistently prefix your integritysetup devices with "is_" it is
# possible to use mdadm.conf(5) glob(7) feature. Example:
# 	DEVICE /dev/mapper/is_*
#
# This is not part of Debian upstream and is currently vermware-specific.
# There is effort to upstream integritytab to Debian, refer to:
# https://salsa.debian.org/cryptsetup-team/cryptsetup/-/merge_requests/22
# Integritytab integration for Debian initially by Melvin Vermeeren, vermware.

References:

Cheers

Edited by Melvin Vermeeren

Merge request reports