Debian Codegraph @

doc/configurable_mount_options.xml

raw
1 <chapter id="mount_options">
2 <title>Configurable mount options</title>
3
4 <para>
5 UDisks comes with a set of predefined mount options for common filesystems used for dynamic mountpoints (i.e., excluding <filename>/etc/fstab</filename> records).
6 This selection has been made with focus on the primary project target: end users, consumers and workstations mostly working with removable media.
7 </para>
8
9 <para>
10 Typically acting as a storage management backend for desktop environments running on user level, the selection comes with a security and data consistency in mind.
11 In other words, user must not be able to access or alter other user's data by allowing insecure mount options or damage the filesystem by experimental filesystem options.
12 For removable media it usually involves synchronous writes to prevent data loss by accidental physical removal of the device while background filesystem sync is running yet the user interface provided no indication of such process.
13 </para>
14
15 <para>
16 Technically UDisks carries a set of allowed mount options for well known filesystems and related set of default options that are subset of the allowed and are always passed to the mount command.
17 Additional mount options can be specified via the <parameter>options</parameter> parameter of the <link linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">org.freedesktop.UDisks2.Filesystem.Mount()</link> method call.
18 These options however need to be subset of allowed mount options for the given filesystem type.
19 </para>
20
21 <para>
22 Since the 2.9.0 UDisks release a new way of overriding builtin set of mount options is supported. This is primarily targeted to sysadmins with system-wide write access (e.g. <filename>/etc/udisks2</filename> or udev rules) and essentially transfers responsibility for security and data consistency to their side.
23 Please keep in mind that wrong combination of options or bad understanding of override levels may lead to inability to mount or false sense of security.
24 Also note that block devices having corresponding records in <filename>/etc/fstab</filename> are excluded from the overrides as the mount options are fully taken from such records just like before.
25 </para>
26
27 <para>
28 No public API has changed, overrides can be defined either via config files or via specific udev rules. UDisks computes mount options on every <link linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Mount()</link> method call, no need to restart or poke the daemon.
29 </para>
30
31 <simplesect><title>Filesystem signature vs. filesystem driver</title>
32 <para>
33 The configurable mount options definition introduced in UDisks 2.9.0 considered the filesystem signature and corresponding filesystem driver an equal definition. Matching filesystem signature identifier was used as a filesystem type for mounting, as is common for most widely used filesystems.
34 </para>
35
36 <para>
37 This has been changed in UDisks 2.10.0 and the configurable mount options gained ability to specify filesystem driver (i.e. a kernel or fuse driver) for a particular filesystem signature, along with a definition of filesystem driver priorities if necessary.
38 In the following paragraphs the term <emphasis>'filesystem signature'</emphasis> typically means <emphasis>'filesystem type'</emphasis> unless stated otherwise.
39 </para>
40 </simplesect>
41
42 <simplesect><title>Basic definitions</title>
43 <para>
44 For the reference this is what the builtin set of options looks like:
45
46 <informalexample>
47 <programlisting>
48 <xi:include href="../data/builtin_mount_options.conf" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"/>
49 </programlisting>
50 </informalexample>
51 </para>
52
53 <para>
54 Typically for each filesystem signature a pair of two sets are defined: <literal>_allow</literal> and <literal>_defaults</literal>.
55 The syntax of each record is <literal>fs_signature[:fs_driver]_key=value1,value2,...</literal> where <literal>fs_signature</literal> denotes the on-disk filesystem signature as detected by <literal>udev/blkid</literal>,
56 an optional <literal>fs_driver</literal> separated by the '<literal>:</literal>' character indicates the filesystem type (<emphasis>driver</emphasis>) to use for the mount call and
57 the <literal>key</literal> is one of the <literal>_allow</literal>, <literal>_defaults</literal> or <literal>_drivers</literal> set of values.
58 In case the optional <literal>fs_driver</literal> part is not specified, it is expected that the name of the filesystem drive equals to filesystem signature, as usual.
59 </para>
60
61 <para>
62 The <literal>_allow</literal> set define mount options ever allowed and considered, the <literal>_defaults</literal> are the target options to use that are then (after further amendmends) passed to the mount command.
63 </para>
64
65 <para>
66 The <literal>_defaults</literal> always need to be a subset of <literal>_allow</literal>. The <literal>_defaults</literal> options are also merged with any extra options passed via the <link linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Mount()</link> method call.
67 </para>
68
69 <para>
70 Optionally, the <literal>_drivers</literal> set defines filesystem driver priorities for the particular filesystem signature to use for the actual mount call, from highest to lowest.
71 Only the <literal>fs_driver</literal> part of the <literal>fs_signature[:fs_driver]_key</literal> triplet should be specified here, separated by comma.
72 </para>
73
74 <para>
75 The <link linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Mount()</link> method call will then attempt to mount the filesystem using computed options defined for the particular filesystem driver separately.
76 Multiple mount attempts are made where in case the filesystem driver is unknown to the kernel, the next one in the list is tried until the operation succeeds. This might potentially lead to extra error messages in the system log from the unsuccessful tries.
77 Distributors are suggested to tweak the priorities according to the supported filesystem drivers.
78 To take advantage of this functionality the <literal>_drivers</literal> record needs to be present, otherwise the extra filesystem driver definitions are ignored and only the base filesystem signature definition matching the filesystem driver name is taken in account.
79 </para>
80
81 <para>
82 Other than the filesystem signature specific options there's also a group of general options that are always merged with fs-specific ones. These include general options like <literal>rw</literal>, <literal>ro</literal>, etc.
83 Let's refer to them as <literal><emphasis>any</emphasis></literal> filesystem options for simplicity in the further text. The result of option set stacking, overrides and merging is referred to as <emphasis>(resulting) computed set of options</emphasis>.
84 </para>
85
86 <para>
87 Apart from the final computed options UDisks always adds the following options due to security concerns: <literal>nodev</literal>, <literal>nosuid</literal>, <literal>uhelper=udisks2</literal> no matter if included in <literal>_allow</literal> or not. These are hardcoded and can't be changed.
88 </para>
89
90 <para>
91 Options that are not allowed in the computed <literal>_allow</literal> set will fail the mount operation with an error.
92 </para>
93 </simplesect>
94
95 <simplesect><title>Unprivileged mounts, UID and GID passing</title>
96 <para>
97 UDisks daemon typically runs as root and spawns the mount command with root privileges while processing requests from unprivileged clients and it needs a way to set proper permissions for the mounted filesystem.
98 This is usually done by passing the <literal>uid</literal> and <literal>gid</literal> mount options that common filesystems honour. UDisks take the D-Bus method caller effective UID and finds its corresponding primary GID.
99 </para>
100
101 <para>
102 Also a <literal>uhelper=udisks2</literal> mount option is added automatically to indicate the umount command to use UDisks again for unmounting when called by an unprivileged user.
103 </para>
104
105 <para>
106 To allow flexibility in mount option naming, two special values are defined as placeholders for aforementioned IDs: <literal>$UID</literal> and <literal>$GID</literal>.
107 These are supposed to be defined as values for specific mount options (typically <literal>uid</literal> and <literal>gid</literal>) within the <literal>_allow</literal> set and are then replaced with numerical values in the late phase of mount option computation.
108 </para>
109
110 <para>
111 It's worth noting that there are few more options whose arguments are being replaced by computed values: <literal>mode</literal> and <literal>dmode</literal>.
112 These options are hardcoded at the moment and its values depend on the udev <literal>UDISKS_FILESYSTEM_SHARED</literal> attribute presence on the block device.
113 </para>
114 </simplesect>
115
116 <simplesect><title>Option set specifics</title>
117 <para>
118 Option sets are composite strings of mount options with or without arguments separated by commas. There's generally no difference from an option string commonly used with the mount command. UDisks brings a couple of specifics for greater flexibility.
119 </para>
120
121 <para>
122 As explained above any particular mount option either defined in the <literal>_defaults</literal> set or passed as an extra argument via the <link linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Mount()</link> method call need to be allowed by the <literal>_allow</literal> set of mount options.
123 There's however a difference in how the option is allowed and what arguments are valid.
124 </para>
125
126 <para>
127 When a considered option is defined with either of the <literal>$UID</literal> or <literal>$GID</literal> values within the <literal>_allow</literal> set (see previous chapter), special rules apply.
128 In case the value of a considered option is the <literal>$UID</literal>/<literal>$GID</literal> placeholder (as is the case of builtin set of options) or no value is specified at all (e.g. the <literal>uid=</literal> string),
129 the <link linkend="gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount">Mount()</link> method caller UID or GID is automatically added.
130 In case a particular value is present (e.g. <literal>uid=1001</literal>) it is only allowed when the caller UID matches the option value.
131 </para>
132
133 <para>
134 In case a considered option is specified explicitly with a value within the <literal>_allow</literal> set no other checks are performed and this <literal>option=value</literal> pair is always allowed.
135 This even bypasses UID and GID checks, except of the <literal>$UID</literal> or <literal>$GID</literal> strings.
136 </para>
137
138 <para>
139 This permits various combinations of caller mount options such as <literal>uid=$UID,uid=ignore</literal> for UDF filesystem where the <literal>uid=ignore</literal> mount options is always allowed yet standard checks (<literal>uid=$UID</literal>) for numerical UID values are still preserved.
140 Similarly, certain numeric UID/GID values may be explicitly allowed this way, allowing non-privileged callers to use predefined IDs (e.g. <literal>uid=1000,uid=1500,uid=ignore</literal> within <literal>_allow</literal>).
141 This also allows to specify arbitrary values permitted, where each pair needs to be specified separately, i.e. <literal>iocharset=utf8,iocharset=iso8859-1,iocharset=iso8859-2</literal>.
142 </para>
143
144 <para>
145 Allowed option defined with no value is treated as any value is permitted but only if passed all checks described above. There's generally no difference between <literal>option</literal> and <literal>option=</literal> (i.e. an empty value) in such definitions.
146 </para>
147 </simplesect>
148
149 <simplesect><title>The config file syntax</title>
150 <para>
151 A sample config file showing rich syntax:
152 <programlisting>
153 [defaults]
154 # common options, applied to any filesystem, always merged with specific filesystem type options
155 defaults=ro
156 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload
157
158 # specific filesystem type options
159 vfat_defaults=uid=$UID,gid=$GID,shortname=mixed,utf8=1,showexec,flush
160 vfat_allow=uid=$UID,gid=$GID,flush,utf8,shortname,umask,dmask,fmask,codepage,iocharset,usefree,showexec
161 ntfs_defaults=uid=$UID,gid=$GID,windows_names
162 ntfs_allow=uid=$UID,gid=$GID,umask,dmask,fmask,locale,norecover,ignore_case,windows_names
163
164 [/dev/disk/by-uuid/18afd8f0-0d86-4d96-8de0-5f92d2ee9800]
165 vfat_defaults=uid=$UID,gid=$GID,noexec
166
167 [/dev/disk/by-label/EFI]
168 vfat_defaults=noexec,umask=111,dmask=000
169 </programlisting>
170 </para>
171
172 <para>
173 The format of the configuration file is an INI-style key-value file parseable by <ulink url="https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html"><type>GKeyFile</type></ulink>.
174 The default location of the file unless specified otherwise during build time is <filename>/etc/udisks2/mount_options.conf</filename>. Sample config file is shipped along the source code.
175 </para>
176
177 <para>
178 The config file may contain multiple groups with a common <code>[defaults]</code> group. One of the new features is an ability to override mount options for particular block device, matched by the block device path. In such case the name of the group is the block device path.
179 It's strongly encouraged to use stable block device identifiers (that is e.g. <filename>/dev/disk/by-*</filename>). No wildcards or glob expansion is performed, for fine-grained matching please use overrides through the custom udev rules.
180 This shouldn't be abused to weaken security requirements though, it's quite easy to fake storage identifiers, more so on removable media.
181 </para>
182 </simplesect>
183
184 <simplesect><title>udev rules overrides</title>
185 <para>
186 Another possibility of overriding mount options is from the udev rules. This brings the flexibility of fine-grained matching by various identifiers and even using external helpers for identification. It's also a less error-prone way than matching by block device symlinks at the config file level.
187 </para>
188
189 <para>
190 This is a separate level of overrides that is positioned on top of the config file level, i.e. definitions coming from udev rules will override respective keys from both the config file level and the base builtin mount options.
191 The override mechanism and rules are no different from the config file level <literal>[defaults]</literal> group. There's just a slight syntactic difference to align with usual udev <literal>ENV</literal> naming conventions, consisting of the <literal>UDISKS_MOUNT_OPTIONS_</literal> key prefix.
192 </para>
193
194 <para>
195 Depending on your distribution specifics there are usually several paths designated for placing custom udev rules, with <filename>/etc/udev/rules.d/</filename> and <filename>/lib/udev/rules.d</filename> being the common ones. It's strongly recommended to make the rules run last, by the <filename>99-</filename> filename prefix.
196 </para>
197
198 <para>
199 Sample udev rules may look as follows:
200 <programlisting>
201 # This file contains custom mount options for udisks 2.x
202 #
203
204 # Skip if not a block device or if requested by other rules
205 #
206 SUBSYSTEM!="block", GOTO="udisks_mount_options_end"
207 ENV{DM_MULTIPATH_DEVICE_PATH}=="1", GOTO="udisks_mount_options_end"
208 ENV{DM_UDEV_DISABLE_OTHER_RULES_FLAG}=="?*", GOTO="udisks_mount_options_end"
209
210
211 # Additional mount options passed to udisksd to allow sysadmins to restrict mount to read-only or "noexec"
212 # for example:
213 #
214 # ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="ro,noexec"
215 # ENV{UDISKS_MOUNT_OPTIONS_ALLOW}="exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload"
216
217 #
218 # Use specific charset for FAT filesystems
219 #
220 # ENV{ID_FS_TYPE}=="vfat", \
221 # ENV{UDISKS_MOUNT_OPTIONS_VFAT_DEFAULTS}="uid=$UID,gid=$GID,shortname=mixed,utf8=0,iocharset=iso8859-15,showexec,flush"
222
223 #
224 # Mount all USB devices read-only
225 #
226 # SUBSYSTEMS=="usb", ENV{ID_FS_USAGE}=="filesystem", ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="ro"
227
228 LABEL="udisks_mount_options_end"
229 </programlisting>
230 </para>
231 </simplesect>
232
233 <simplesect><title>Levels of overrides</title>
234 <para>
235 Levels from lower to higher:
236 <itemizedlist>
237 <listitem>builtin options</listitem>
238 <listitem>global config file (i.e. <filename>/etc/udisks2/mount_options.conf</filename>)</listitem>
239 <listitem>udev rules</listitem>
240 </itemizedlist>
241 </para>
242
243 <para>
244 Higher level options always fully override lower levels.
245 </para>
246
247 <para>
248 While the builtin options are always present, upper levels are optional.
249 </para>
250
251 <para>
252 Each level may consist of a common group and block device specific groups.
253 </para>
254 </simplesect>
255
256 <simplesect><title>Rules computation</title>
257 <para>
258 This is the most important part to understand as badly formulated options may lead to unforeseen consequences.
259 </para>
260
261 <para>
262 As a general rule, set of options from higher levels always fully replace (<emphasis>cover</emphasis>, <emphasis>override</emphasis>) options from lower levels.
263 This works on per-set basis, i.e. separately for each of the <literal>_allow</literal> and <literal>_defaults</literal> sets.
264 Please pay attention to allowance of the mount options overridden in the <literal>_defaults</literal> set at a given level without overriding the <literal>_allow</literal> set at the same place - lower levels may not allow all the options.
265 </para>
266
267 <para>
268 First, overrides are computed within each level. At a given level, block device specific options take higher priority over the common options (the <code>[defaults]</code> group) and fully override them.
269 </para>
270
271 <para>
272 As a second step, overrides are computed vertically across all levels, from higher down to lower ones, again separately per-set basis. At this point, there are no block device specific options as they have been computed in the previous step.
273 </para>
274
275 <para>
276 The filesystem type specific options and common options (<literal><emphasis>any</emphasis></literal>) are computed separately across all levels per-set basis.
277 </para>
278
279 <para>
280 As a final step, when all sets are layered and computed onto a flat level, filesystem specific options and common options are merged together.
281 </para>
282
283 <para>
284 See the examples for further illustration.
285 </para>
286 </simplesect>
287
288 <simplesect><title>Examples</title>
289 <para>
290 <example>
291 <title>Disable <literal>flush</literal> on vfat and <literal>windows_names</literal> on ntfs</title>
292 <programlisting>
293 [defaults]
294 vfat_defaults=uid=$UID,gid=$GID,shortname=mixed,utf8=1,showexec
295 ntfs_defaults=uid=$UID,gid=$GID
296 </programlisting>
297 <note>There's no way to specify subset addition or subtraction, particular sets need to be overridden fully. I.e. take the builtin mount options and remove/add options as you like.</note>
298 </example>
299
300 <example>
301 <title>Force all mounts read only</title>
302 <programlisting>
303 [defaults]
304 defaults=ro
305 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
306 </programlisting>
307 <note>Note that this doesn't apply to fstab mounts where mount options are fully respected.</note>
308 </example>
309
310 <example>
311 <title>Force all mounts read only except of my trusty USB drive</title>
312 <programlisting>
313 [defaults]
314 defaults=ro
315 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
316
317 [/dev/disk/by-uuid/18afd8f0-0d86-4d96-8de0-5f92d2ee9800]
318 defaults=
319 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload
320 </programlisting>
321 <note>Note that this possesses a security risk as it's rather easy to fake commonly used identifiers like UUIDs, labels, etc.</note>
322 </example>
323
324 <example>
325 <title>Much safer way of matching my trusty USB drive</title>
326 <programlisting>
327 [defaults]
328 defaults=ro
329 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
330 </programlisting>
331
332 <programlisting>
333 SUBSYSTEM!="block", GOTO="udisks_mount_options_end"
334 ENV{DM_MULTIPATH_DEVICE_PATH}=="1", GOTO="udisks_mount_options_end"
335 ENV{DM_UDEV_DISABLE_OTHER_RULES_FLAG}=="?*", GOTO="udisks_mount_options_end"
336
337 ENV{ID_VENDOR}=="TrustyQualityInc", ENV{ID_MODEL}=="Unbreakable USB Stick", \
338 ENV{ID_SERIAL}=="360014055282611e2e7440198ca5d8ceb", \
339 ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="rw", \
340 ENV{UDISKS_MOUNT_OPTIONS_ALLOW}="exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload"
341
342 LABEL="udisks_mount_options_end"
343 </programlisting>
344 </example>
345
346 <example>
347 <title>Allow fine-grained control over UIDs</title>
348 <programlisting>
349 [defaults]
350 vfat_allow=uid=1001,uid=1005,gid=$GID,flush,utf8,shortname,umask,dmask,fmask,codepage,iocharset,usefree,showexec
351 </programlisting>
352 <note>Notice that the usual <literal>uid=$UID</literal> option is missing from the <literal>vfat_allow</literal> set and specific allowed UIDs are the only ones defined.
353 As the <literal>vfat_defaults</literal> set is not being overridden here and still carries the <literal>uid=$UID</literal> mount option that gets automatically replaced by caller effective UID, the computed option value must match any of the <literal>vfat_allow</literal> options,
354 thus the whole mount operation will be denied if the UIDs don't match.</note>
355 </example>
356
357 <example>
358 <title>Multiple filesystem drivers for a common filesystem signature</title>
359 <programlisting>
360 [defaults]
361 # the legacy ntfs kernel driver and the ntfs-3g fuse driver
362 # the usual case where the filesystem signature corresponds with the filesystem driver
363 ntfs_defaults=uid=$UID,gid=$GID,windows_names
364 ntfs_allow=uid=$UID,gid=$GID,umask,dmask,fmask,locale,norecover,ignore_case,windows_names,compression,nocompression,big_writes
365
366 # ntfs3 kernel driver
367 # different filesystem driver for a common filesystem signature
368 ntfs:ntfs3_defaults=uid=$UID,gid=$GID
369 ntfs:ntfs3_allow=uid=$UID,gid=$GID,umask,dmask,fmask,iocharset,discard,nodiscard,sparse,nosparse,hidden,nohidden,sys_immutable,nosys_immutable,showmeta,noshowmeta,prealloc,noprealloc
370
371 # filesystem driver order for the specified filesystem signature
372 # required to actually use the extra definitions
373 ntfs_drivers=ntfs3,ntfs
374 </programlisting>
375 </example>
376
377 </para>
378 </simplesect>
379
380 </chapter>