Debian Codegraph @

upstream/debian-trixie/man5/integritytab.5

raw
1 '\" t
2 .TH "INTEGRITYTAB" "5" "" "systemd 257.13" "integritytab"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 integritytab \- Configuration for integrity block devices
24 .SH "SYNOPSIS"
25 .PP
26 /etc/integritytab
27 .SH "DESCRIPTION"
28 .PP
29 The
30 /etc/integritytab
31 file describes integrity protected block devices that are set up during system boot\&.
32 .PP
33 Empty lines and lines starting with the
34 "#"
35 character are ignored\&. Each of the remaining lines describes one verity integrity protected block device\&. Fields are delimited by white space\&.
36 .PP
37 Each line is in the form
38 .sp
39 .if n \{\
40 .RS 4
41 .\}
42 .nf
43 \fIvolume\-name\fR \fIblock\-device\fR
44 \fI[keyfile|\-]\fR \fI[options|\-]\fR
45 .fi
46 .if n \{\
47 .RE
48 .\}
49 .sp
50 The first two fields are mandatory, the remaining two are optional and only required if user specified non\-default options during integrity format\&.
51 .PP
52 The first field contains the name of the resulting integrity volume; its block device is set up below
53 /dev/mapper/\&.
54 .PP
55 The second field contains a path to the underlying block device, or a specification of a block device via
56 "UUID="
57 followed by the UUID,
58 "PARTUUID="
59 followed by the partition UUID,
60 "LABEL="
61 followed by the label,
62 "PARTLABEL="
63 followed by the partition label\&.
64 .PP
65 The third field if present contains an absolute filename path to a key file or a
66 "\-"
67 to specify none\&. When the filename is present, the "integrity\-algorithm" defaults to
68 "hmac\-sha256"
69 with the key length derived from the number of bytes in the key file\&. At this time the only supported integrity algorithm when using key file is hmac\-sha256\&. The maximum size of the key file is 4096 bytes\&.
70 .PP
71 The fourth field, if present, is a comma\-delimited list of options or a
72 "\-"
73 to specify none\&. The following options are recognized:
74 .PP
75 \fBallow\-discards\fR
76 .RS 4
77 Allow the use of discard (TRIM) requests for the device\&. This option is available since the Linux kernel version 5\&.7\&.
78 .sp
79 Added in version 250\&.
80 .RE
81 .PP
82 \fBmode=(journal|bitmap|direct)\fR
83 .RS 4
84 Enable journaled, bitmapped or direct (passthrough) mode\&. Journaled mode is the default when this option is not specified\&. It provides safety against crashes, but can be slow because all data has to be written twice\&. Bitmap mode is more efficient since it requires only a single write, but it is less reliable because if data corruption happens when the machine crashes, it might not be detected\&. Direct mode disables the journal and the bitmap\&. Corresponds to the "direct writes" mode documented in
85 \m[blue]\fBthe dm\-integrity documentation\fR\m[]\&\s-2\u[1]\d\s+2\&. Note that without a journal, if there is a crash, it is possible that the integrity tags and data will not match\&. If used, the journal\-* options below will have no effect if passed\&.
86 .sp
87 Added in version 254\&.
88 .RE
89 .PP
90 \fBjournal\-watermark=[0\&.\&.100]%\fR
91 .RS 4
92 Journal watermark in percent\&. When the journal percentage exceeds this watermark, the journal flush will be started\&. Setting a value of "0%" uses default value\&.
93 .sp
94 Added in version 250\&.
95 .RE
96 .PP
97 \fBjournal\-commit\-time=[0\&.\&.N]\fR
98 .RS 4
99 Commit time in milliseconds\&. When this time passes (and no explicit flush operation was issued), the journal is written\&. Setting a value of zero uses default value\&.
100 .sp
101 Added in version 250\&.
102 .RE
103 .PP
104 \fBdata\-device=/dev/disk/by\-\&.\&.\&.\fR
105 .RS 4
106 Specify a separate block device that contains existing data\&. The second field specified in the integritytab for block device then will contain calculated integrity tags and journal for data\-device, but not the end user data\&.
107 .sp
108 Added in version 250\&.
109 .RE
110 .PP
111 \fBintegrity\-algorithm=[crc32c|crc32|xxhash64|sha1|sha256|hmac\-sha256]\fR
112 .RS 4
113 The algorithm used for integrity checking\&. The default is crc32c\&. Must match option used during format\&.
114 .sp
115 Added in version 250\&.
116 .RE
117 .PP
118 At early boot and when the system manager configuration is reloaded, this file is translated into native systemd units by
119 \fBsystemd-integritysetup-generator\fR(8)\&.
120 .SH "EXAMPLES"
121 .PP
122 \fBExample\ \&1.\ \&/etc/integritytab\fR
123 .PP
124 Set up two integrity protected block devices\&.
125 .sp
126 .if n \{\
127 .RS 4
128 .\}
129 .nf
130 home PARTUUID=4973d0b8\-1b15\-c449\-96ec\-94bab7f6a7b8 \- journal\-commit\-time=10,allow\-discards,journal\-watermark=55%
131 data PARTUUID=5d4b1808\-be76\-774d\-88af\-03c4c3a41761 \- allow\-discards
132 .fi
133 .if n \{\
134 .RE
135 .\}
136 .PP
137 \fBExample\ \&2.\ \&/etc/integritytab\fR
138 .PP
139 Set up 1 integrity protected block device using defaults
140 .sp
141 .if n \{\
142 .RS 4
143 .\}
144 .nf
145 home PARTUUID=4973d0b8\-1b15\-c449\-96ec\-94bab7f6a7b8
146 .fi
147 .if n \{\
148 .RE
149 .\}
150 .PP
151 \fBExample\ \&3.\ \&/etc/integritytab\fR
152 .PP
153 Set up 1 integrity device using existing data block device which contains user data
154 .sp
155 .if n \{\
156 .RS 4
157 .\}
158 .nf
159 home PARTUUID=4973d0b8\-1b15\-c449\-96ec\-94bab7f6a7b8 \- data\-device=/dev/disk/by\-uuid/9276d9c0\-d4e3\-4297\-b4ff\-3307cd0d092f
160 .fi
161 .if n \{\
162 .RE
163 .\}
164 .PP
165 \fBExample\ \&4.\ \&/etc/integritytab\fR
166 .PP
167 Set up 1 integrity device using a HMAC key file using defaults
168 .sp
169 .if n \{\
170 .RS 4
171 .\}
172 .nf
173 home PARTUUID=4973d0b8\-1b15\-c449\-96ec\-94bab7f6a7b8 /etc/hmac\&.key
174 .fi
175 .if n \{\
176 .RE
177 .\}
178 .SH "SEE ALSO"
179 .PP
180 \fBsystemd\fR(1), \[email protected]\fR(8), \fBsystemd-integritysetup-generator\fR(8), \fBintegritysetup\fR(8)
181 .SH "NOTES"
182 .IP " 1." 4
183 the dm-integrity documentation
184 .RS 4
185 \%https://docs.kernel.org/admin-guide/device-mapper/dm-integrity.html
186 .RE