man/integritysetup.8.adoc

   1 = integritysetup(8)
   2 :doctype: manpage
   3 :manmanual: Maintenance Commands
   4 :mansource: integritysetup {release-version}
   5 :man-linkstyle: pass:[blue R < >]
   6
   7 == NAME
   8
   9 integritysetup - manage dm-integrity (block level integrity) volumes
  10
  11 == SYNOPSIS
  12
  13 *integritysetup <action> [<options>] <action args>*
  14
  15 == DESCRIPTION
  16
  17 Integritysetup is used to configure dm-integrity managed device-mapper
  18 mappings.
  19
  20 Device-mapper integrity target provides read-write transparent integrity
  21 checking of block devices. The dm-integrity target emulates an additional
  22 data integrity field per-sector. You can use this additional field
  23 directly with integritysetup utility, or indirectly (for authenticated
  24 encryption) through cryptsetup.
  25
  26 == BASIC ACTIONS
  27
  28 Integritysetup supports these operations:
  29
  30 === FORMAT
  31 *format <device>*
  32
  33 Formats <device> (calculates space and dm-integrity superblock and wipes
  34 the device).
  35
  36 *<options>* can be [--data-device, --batch-mode, --no-wipe,
  37 --journal-size, --interleave-sectors, --tag-size, --integrity,
  38 --integrity-key-size, --integrity-key-file, --sector-size,
  39 --progress-frequency, --progress-json].
  40
  41 === OPEN
  42 *open <device> <name>* +
  43 create <name> <device> (*OBSOLETE syntax*)
  44
  45 Open a mapping with <name> backed by device <device>.
  46
  47 *<options>* can be [--data-device, --batch-mode, --journal-watermark,
  48 --journal-commit-time, --buffer-sectors, --integrity,
  49 --integrity-key-size, --integrity-key-file, --integrity-no-journal,
  50 --integrity-recalculate,
  51 --integrity-recalculate-reset,--integrity-recovery-mode,
  52 --allow-discards].
  53
  54 === CLOSE
  55 *close <name>* +
  56 remove <name> (*OBSOLETE syntax*)
  57
  58 Removes existing mapping <name>.
  59
  60 *<options>* can be [--deferred] or [--cancel-deferred]
  61
  62 === STATUS
  63 *status <name>*
  64
  65 Reports status for the active integrity mapping <name>.
  66
  67 === DUMP
  68 *dump <device>*
  69
  70 Reports parameters from on-disk stored superblock.
  71
  72 === RESIZE
  73 *resize <name>*
  74
  75 Resizes an active mapping <name>.
  76
  77 If --size (in 512-bytes sectors) or --device-size are not specified, the
  78 size is computed from the underlying device. After resize, the
  79 *recalculating* flag is set. If --wipe flag is set and the size of the
  80 device is increased, the newly added section will be wiped.
  81
  82 Increasing the size of integrity volumes is available since the Linux
  83 kernel version 5.7, shrinking should work on older kernels too.
  84
  85 *<options>* can be [--size, --device-size, --wipe].
  86
  87 == OPTIONS
  88 *--progress-frequency <seconds>*::
  89 Print separate line every <seconds> with wipe progress.
  90
  91 *--progress-json*::
  92 Prints wipe progress data in json format suitable mostly for machine
  93 processing. It prints separate line every half second (or based on
  94 --progress-frequency value). The JSON output looks as follows during
  95 wipe progress (except it's compact single line):
  96 +
  97 ....
  98 {
  99   "device":"/dev/sda"       // backing device or file
 100   "device_bytes":"8192",    // bytes wiped so far
 101   "device_size":"44040192", // total bytes to wipe
 102   "speed":"126877696",      // calculated speed in bytes per second (based on progress so far)
 103   "eta_ms":"2520012"        // estimated time to finish wipe in milliseconds
 104   "time_ms":"5561235"       // total time spent wiping device in milliseconds
 105 }
 106 ....
 107 +
 108 Note on numbers in JSON output: Due to JSON parsers limitations all
 109 numbers are represented in a string format due to need of full 64bit
 110 unsigned integers.
 111
 112 *--no-wipe*::
 113 Do not wipe the device after format. A device that is not initially
 114 wiped will contain invalid checksums.
 115
 116 *--wipe*::
 117 Wipe the newly allocated area after resize to bigger size. If this
 118 flag is not set, checksums will be calculated for the data previously
 119 stored in the newly allocated area.
 120
 121 *--journal-size, -j BYTES*::
 122 Size of the journal.
 123
 124 *--interleave-sectors SECTORS*::
 125 The number of interleaved sectors.
 126
 127 *--integrity-recalculate*::
 128 Automatically recalculate integrity tags in kernel on activation. The
 129 device can be used during automatic integrity recalculation but
 130 becomes fully integrity protected only after the background operation
 131 is finished. This option is available since the Linux kernel version
 132 4.19.
 133
 134 *--integrity-recalculate-reset*::
 135 Restart recalculation from the beginning of the device. It can be used
 136 to change the integrity checksum function. Note it does not change the
 137 tag length. This option is available since the Linux kernel version
 138 5.13.
 139
 140 *--journal-watermark PERCENT*::
 141 Journal watermark in percents. When the size of the journal exceeds
 142 this watermark, the journal flush will be started.
 143
 144 *--journal-commit-time MS*::
 145 Commit time in milliseconds. When this time passes (and no explicit
 146 flush operation was issued), the journal is written.
 147
 148 *--tag-size, -t BYTES*::
 149 Size of the integrity tag per-sector (here the integrity function will
 150 store authentication tag).
 151 +
 152 *NOTE:* The size can be smaller that output size of the hash function,
 153 in that case only part of the hash will be stored.
 154
 155 *--data-device <data_device>*::
 156 Specify a separate data device that contains existing data. The
 157 <device> then will contain calculated integrity tags and journal for
 158 data on <data_device>.
 159 +
 160 *NOTE:* To not wipe the data device after initial format, also specify
 161 --no-wipe option and activate with --integrity-recalculate to
 162 automatically recalculate integrity tags.
 163
 164 *--sector-size, -s BYTES*::
 165 Sector size (power of two: 512, 1024, 2048, 4096).
 166
 167 *--buffer-sectors SECTORS*::
 168 The number of sectors in one buffer.
 169 +
 170 The tag area is accessed using buffers, the large buffer size means that
 171 the I/O size will be larger, but there could be less I/Os issued.
 172
 173 *--integrity, -I ALGORITHM*::
 174 Use internal integrity calculation (standalone mode). The integrity
 175 algorithm can be CRC (crc32c/crc32), non-cryptographic hash function
 176 (xxhash64) or hash function (sha1, sha256).
 177 +
 178 For HMAC (hmac-sha256) you have also to specify an integrity key and its
 179 size.
 180
 181 *--integrity-key-size BYTES*::
 182 The size of the data integrity key. Maximum is 4096 bytes.
 183
 184 *--integrity-key-file FILE*::
 185 The file with the integrity key.
 186
 187 *--integrity-no-journal, -D*::
 188 Disable journal for integrity device.
 189
 190 *--integrity-bitmap-mode. -B*::
 191 Use alternate bitmap mode (available since Linux kernel 5.2) where
 192 dm-integrity uses bitmap instead of a journal. If a bit in the bitmap
 193 is 1, the corresponding region's data and integrity tags are not
 194 synchronized - if the machine crashes, the unsynchronized regions will
 195 be recalculated. The bitmap mode is faster than the journal mode,
 196 because we don't have to write the data twice, but it is also less
 197 reliable, because if data corruption happens when the machine crashes,
 198 it may not be detected.
 199
 200 *--bitmap-sectors-per-bit SECTORS*::
 201 Number of 512-byte sectors per bitmap bit, the value must be power of
 202 two.
 203
 204 *--bitmap-flush-time MS*::
 205 Bitmap flush time in milliseconds.
 206 +
 207 *WARNING:*::
 208 In case of a crash, it is possible that the data and integrity tag
 209 doesn't match if the journal is disabled.
 210
 211 *--integrity-recovery-mode. -R*::
 212 Recovery mode (no journal, no tag checking).
 213
 214 *NOTE:* The following options are intended for testing purposes only.:
 215 Using journal encryption does not make sense without encryption the
 216 data, these options are internally used in authenticated disk
 217 encryption with *cryptsetup(8)*.
 218
 219 *--journal-integrity ALGORITHM*::
 220 Integrity algorithm for journal area. See --integrity option for
 221 detailed specification.
 222
 223 *--journal-integrity-key-size BYTES*::
 224 The size of the journal integrity key. Maximum is 4096 bytes.
 225
 226 *--journal-integrity-key-file FILE*::
 227 The file with the integrity key.
 228
 229 *--journal-crypt ALGORITHM*::
 230 Encryption algorithm for journal data area. You can use a block cipher
 231 here such as cbc-aes or a stream cipher, for example, chacha20 or
 232 ctr-aes.
 233
 234 *--journal-crypt-key-size BYTES*::
 235 The size of the journal encryption key. Maximum is 4096 bytes.
 236
 237 *--journal-crypt-key-file FILE*::
 238 The file with the journal encryption key.
 239
 240 *--allow-discards*::
 241 Allow the use of discard (TRIM) requests for the device. This option
 242 is available since the Linux kernel version 5.7.
 243
 244 *--deferred*::
 245 Defers device removal in *close* command until the last user closes
 246 it.
 247
 248 *--cancel-deferred*::
 249 Removes a previously configured deferred device removal in *close*
 250 command.
 251
 252 *--verbose, -v*::
 253 Print more information on command execution.
 254
 255 *--debug*::
 256 Run in debug mode with full diagnostic logs. Debug output lines are
 257 always prefixed by *#*.
 258
 259 *--version, -V*::
 260 Show the program version.
 261
 262 *--batch-mode, -q*::
 263 Do not ask for confirmation.
 264
 265 *--usage*::
 266 Show short option help.
 267
 268 *--help, -?*::
 269 Show help text and default parameters.
 270
 271 == LEGACY COMPATIBILITY OPTIONS
 272
 273 *WARNING:*::
 274 Do not use these options until you need compatibility with specific
 275 old kernel.
 276
 277 *--integrity-legacy-padding*::
 278 Use inefficient legacy padding.
 279
 280 *--integrity-legacy-hmac*::
 281 Use old flawed HMAC calculation (also does not protect superblock).
 282
 283 *--integrity-legacy-recalculate*::
 284 Allow insecure recalculating of volumes with HMAC keys (recalculation
 285 offset in superblock is not protected).
 286
 287 == RETURN CODES
 288
 289 Integritysetup returns *0* on success and a non-zero value on error.
 290
 291 Error codes are: *1* wrong parameters, *2* no permission, *3* out of memory,
 292 *4* wrong device specified, *5* device already exists or device is busy.
 293
 294 == NOTES
 295 The dm-integrity target is available since Linux kernel version 4.12.
 296
 297 Format and activation of an integrity device always require superuser
 298 privilege because the superblock is calculated and handled in
 299 dm-integrity kernel target.
 300
 301 == EXAMPLES
 302
 303 Format the device with default standalone mode (CRC32C):
 304
 305 *integritysetup format <device>*
 306
 307 Open the device with default parameters:
 308
 309 *integritysetup open <device> test*
 310
 311 Format the device in standalone mode for use with HMAC(SHA256):
 312
 313 *integritysetup format <device> --tag-size 32 --integrity hmac-sha256
 314 --integrity-key-file <keyfile> --integrity-key-size <key_bytes>*
 315
 316 Open (activate) the device with HMAC(SHA256) and HMAC key in file:
 317
 318 *integritysetup open <device> test --integrity hmac-sha256
 319 --integrity-key-file <keyfile> --integrity-key-size <key_bytes>*
 320
 321 Dump dm-integrity superblock information:
 322
 323 *integritysetup dump <device>*
 324
 325 == DM-INTEGRITY ON-DISK FORMAT
 326
 327 The on-disk format specification available at
 328 https://gitlab.com/cryptsetup/cryptsetup/wikis/DMIntegrity[*DMIntegrity*] page.
 329
 330 == AUTHORS
 331
 332 The integritysetup tool is written by mailto:gmazyland@gmail.com[Milan Broz].
 333
 334 include::man/common_footer.adoc[]