1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>Configurable mount options: UDisks Reference Manual</title>
<meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
<link rel="home" href="index.html" title="UDisks Reference Manual">
<link rel="up" href="overview.html" title="Part I. Manual pages and Overview">
<link rel="prev" href="udisks2_lsm.conf.5.html" title="udisks2_lsm.conf">
<link rel="next" href="ref-dbus.html" title="Part II. D-Bus API Reference">
<meta name="generator" content="GTK-Doc V1.35.1 (XML mode)">
<link rel="stylesheet" href="style.css" type="text/css">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
<td width="100%" align="left" class="shortcuts"></td>
<td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
<td><a accesskey="u" href="overview.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
<td><a accesskey="p" href="udisks2_lsm.conf.5.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
<td><a accesskey="n" href="ref-dbus.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
</tr></table>
<div class="chapter">
<div class="titlepage"><div><div><h2 class="title">
<a name="mount_options"></a>Configurable mount options</h2></div></div></div>
<p>
UDisks comes with a set of predefined mount options for common filesystems used for dynamic mountpoints (i.e., excluding <code class="filename">/etc/fstab</code> records).
This selection has been made with focus on the primary project target: end users, consumers and workstations mostly working with removable media.
</p>
<p>
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.
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.
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.
</p>
<p>
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.
Additional mount options can be specified via the <em class="parameter"><code>options</code></em> parameter of the <a class="link" href="gdbus-org.freedesktop.UDisks2.Filesystem.html#gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount" title="The Mount() method">org.freedesktop.UDisks2.Filesystem.Mount()</a> method call.
These options however need to be subset of allowed mount options for the given filesystem type.
</p>
<p>
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. <code class="filename">/etc/udisks2</code> or udev rules) and essentially transfers responsibility for security and data consistency to their side.
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.
Also note that block devices having corresponding records in <code class="filename">/etc/fstab</code> are excluded from the overrides as the mount options are fully taken from such records just like before.
</p>
<p>
No public API has changed, overrides can be defined either via config files or via specific udev rules. UDisks computes mount options on every <a class="link" href="gdbus-org.freedesktop.UDisks2.Filesystem.html#gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount" title="The Mount() method">Mount()</a> method call, no need to restart or poke the daemon.
</p>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.7"></a>Filesystem signature vs. filesystem driver</h2></div></div></div>
<p>
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.
</p>
<p>
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.
In the following paragraphs the term <span class="emphasis"><em>'filesystem signature'</em></span> typically means <span class="emphasis"><em>'filesystem type'</em></span> unless stated otherwise.
</p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.8"></a>Basic definitions</h2></div></div></div>
<p>
For the reference this is what the builtin set of options looks like:
</p>
<div class="informalexample">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="p">[</span><span class="n">defaults</span><span class="p">]</span>
<span class="n">allow</span><span class="o">=</span><span class="n">exec</span><span class="p">,</span><span class="n">noexec</span><span class="p">,</span><span class="n">nodev</span><span class="p">,</span><span class="n">nosuid</span><span class="p">,</span><span class="n">atime</span><span class="p">,</span><span class="n">noatime</span><span class="p">,</span><span class="n">nodiratime</span><span class="p">,</span><span class="n">relatime</span><span class="p">,</span><span class="n">strictatime</span><span class="p">,</span><span class="n">lazytime</span><span class="p">,</span><span class="n">ro</span><span class="p">,</span><span class="n">rw</span><span class="p">,</span><span class="n">sync</span><span class="p">,</span><span class="n">dirsync</span><span class="p">,</span><span class="n">noload</span><span class="p">,</span><span class="n">acl</span><span class="p">,</span><span class="n">nosymfollow</span>
<span class="n">vfat_defaults</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">shortname</span><span class="o">=</span><span class="n">mixed</span><span class="p">,</span><span class="n">utf8</span><span class="o">=</span><span class="mi">1</span><span class="p">,</span><span class="n">showexec</span><span class="p">,</span><span class="n">flush</span>
<span class="n">vfat_allow</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">flush</span><span class="p">,</span><span class="n">utf8</span><span class="p">,</span><span class="n">shortname</span><span class="p">,</span><span class="n">umask</span><span class="p">,</span><span class="n">dmask</span><span class="p">,</span><span class="n">fmask</span><span class="p">,</span><span class="n">codepage</span><span class="p">,</span><span class="n">iocharset</span><span class="p">,</span><span class="n">usefree</span><span class="p">,</span><span class="n">showexec</span>
<span class="cp"># common options for both the native kernel driver and exfat-fuse</span>
<span class="n">exfat_defaults</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">iocharset</span><span class="o">=</span><span class="n">utf8</span><span class="p">,</span><span class="n">errors</span><span class="o">=</span><span class="n">remount</span><span class="o">-</span><span class="n">ro</span>
<span class="n">exfat_allow</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">dmask</span><span class="p">,</span><span class="n">errors</span><span class="p">,</span><span class="n">fmask</span><span class="p">,</span><span class="n">iocharset</span><span class="p">,</span><span class="n">namecase</span><span class="p">,</span><span class="n">umask</span>
<span class="cp"># 'ntfs' signature, definitions for the legacy ntfs kernel driver and the ntfs-3g fuse driver</span>
<span class="nl">ntfs</span><span class="p">:</span><span class="n">ntfs_defaults</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">windows_names</span>
<span class="nl">ntfs</span><span class="p">:</span><span class="n">ntfs_allow</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">umask</span><span class="p">,</span><span class="n">dmask</span><span class="p">,</span><span class="n">fmask</span><span class="p">,</span><span class="n">locale</span><span class="p">,</span><span class="n">norecover</span><span class="p">,</span><span class="n">ignore_case</span><span class="p">,</span><span class="n">windows_names</span><span class="p">,</span><span class="n">compression</span><span class="p">,</span><span class="n">nocompression</span><span class="p">,</span><span class="n">big_writes</span>
<span class="cp"># 'ntfs' signature, the new 'ntfs3' kernel driver</span>
<span class="nl">ntfs</span><span class="p">:</span><span class="n">ntfs3_defaults</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span>
<span class="nl">ntfs</span><span class="p">:</span><span class="n">ntfs3_allow</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">umask</span><span class="p">,</span><span class="n">dmask</span><span class="p">,</span><span class="n">fmask</span><span class="p">,</span><span class="n">iocharset</span><span class="p">,</span><span class="n">discard</span><span class="p">,</span><span class="n">nodiscard</span><span class="p">,</span><span class="n">sparse</span><span class="p">,</span><span class="n">nosparse</span><span class="p">,</span><span class="n">hidden</span><span class="p">,</span><span class="n">nohidden</span><span class="p">,</span><span class="n">sys_immutable</span><span class="p">,</span><span class="n">nosys_immutable</span><span class="p">,</span><span class="n">showmeta</span><span class="p">,</span><span class="n">noshowmeta</span><span class="p">,</span><span class="n">prealloc</span><span class="p">,</span><span class="n">noprealloc</span><span class="p">,</span><span class="n">hide_dot_files</span><span class="p">,</span><span class="n">nohide_dot_files</span><span class="p">,</span><span class="n">windows_names</span><span class="p">,</span><span class="n">nocase</span><span class="p">,</span><span class="k">case</span>
<span class="cp"># define order of filesystem driver priorities for the actual mount call,</span>
<span class="cp"># required definition for non-matching driver names</span>
<span class="no">ntfs_drivers</span><span class="o">=</span><span class="no">ntfs3</span><span class="p">,</span><span class="no">ntfs</span>
<span class="no">iso9660_defaults</span><span class="o">=</span><span class="no">uid</span><span class="o">=</span><span class="no">$UID</span><span class="p">,</span><span class="no">gid</span><span class="o">=</span><span class="no">$GID</span><span class="p">,</span><span class="no">iocharset</span><span class="o">=</span><span class="no">utf8</span><span class="p">,</span><span class="no">mode</span><span class="o">=</span><span class="mo">0400</span><span class="p">,</span><span class="no">dmode</span><span class="o">=</span><span class="mo">0500</span>
<span class="no">iso9660_allow</span><span class="o">=</span><span class="no">uid</span><span class="o">=</span><span class="no">$UID</span><span class="p">,</span><span class="no">gid</span><span class="o">=</span><span class="no">$GID</span><span class="p">,</span><span class="no">norock</span><span class="p">,</span><span class="no">nojoliet</span><span class="p">,</span><span class="no">iocharset</span><span class="p">,</span><span class="no">mode</span><span class="p">,</span><span class="no">dmode</span><span class="p">,</span><span class="no">map</span><span class="p">,</span><span class="no">check</span>
<span class="no">udf_defaults</span><span class="o">=</span><span class="no">uid</span><span class="o">=</span><span class="no">$UID</span><span class="p">,</span><span class="no">gid</span><span class="o">=</span><span class="no">$GID</span><span class="p">,</span><span class="no">iocharset</span><span class="o">=</span><span class="no">utf8</span>
<span class="no">udf_allow</span><span class="o">=</span><span class="no">uid</span><span class="o">=</span><span class="no">$UID</span><span class="p">,</span><span class="no">gid</span><span class="o">=</span><span class="no">$GID</span><span class="p">,</span><span class="no">iocharset</span><span class="p">,</span><span class="no">utf8</span><span class="p">,</span><span class="no">umask</span><span class="p">,</span><span class="no">mode</span><span class="p">,</span><span class="no">dmode</span><span class="p">,</span><span class="no">unhide</span><span class="p">,</span><span class="no">undelete</span>
<span class="no">hfsplus_defaults</span><span class="o">=</span><span class="no">uid</span><span class="o">=</span><span class="no">$UID</span><span class="p">,</span><span class="no">gid</span><span class="o">=</span><span class="no">$GID</span><span class="p">,</span><span class="no">nls</span><span class="o">=</span><span class="no">utf8</span>
<span class="no">hfsplus_allow</span><span class="o">=</span><span class="no">uid</span><span class="o">=</span><span class="no">$UID</span><span class="p">,</span><span class="no">gid</span><span class="o">=</span><span class="no">$GID</span><span class="p">,</span><span class="no">creator</span><span class="p">,</span><span class="no">type</span><span class="p">,</span><span class="no">umask</span><span class="p">,</span><span class="no">session</span><span class="p">,</span><span class="no">part</span><span class="p">,</span><span class="no">decompose</span><span class="p">,</span><span class="no">nodecompose</span><span class="p">,</span><span class="no">force</span><span class="p">,</span><span class="no">nls</span>
<span class="no">btrfs_allow</span><span class="o">=</span><span class="no">compress</span><span class="p">,</span><span class="no">compress</span><span class="o">-</span><span class="no">force</span><span class="p">,</span><span class="no">datacow</span><span class="p">,</span><span class="no">nodatacow</span><span class="p">,</span><span class="no">datasum</span><span class="p">,</span><span class="no">nodatasum</span><span class="p">,</span><span class="no">autodefrag</span><span class="p">,</span><span class="no">noautodefrag</span><span class="p">,</span><span class="no">degraded</span><span class="p">,</span><span class="no">device</span><span class="p">,</span><span class="no">discard</span><span class="p">,</span><span class="no">nodiscard</span><span class="p">,</span><span class="no">subvol</span><span class="p">,</span><span class="no">subvolid</span><span class="p">,</span><span class="no">space_cache</span>
<span class="no">f2fs_allow</span><span class="o">=</span><span class="no">discard</span><span class="p">,</span><span class="no">nodiscard</span><span class="p">,</span><span class="no">compress_algorithm</span><span class="p">,</span><span class="no">compress_log_size</span><span class="p">,</span><span class="no">compress_extension</span><span class="p">,</span><span class="no">compress_chksum</span><span class="p">,</span><span class="no">alloc_mode</span><span class="p">,</span><span class="no">atgc</span><span class="p">,</span><span class="no">gc_merge</span><span class="p">,</span><span class="no">nogc_merge</span>
<span class="no">xfs_allow</span><span class="o">=</span><span class="no">discard</span><span class="p">,</span><span class="no">nodiscard</span><span class="p">,</span><span class="no">inode32</span><span class="p">,</span><span class="no">largeio</span><span class="p">,</span><span class="no">wsync</span>
<span class="no">reiserfs_allow</span><span class="o">=</span><span class="no">hashed_relocation</span><span class="p">,</span><span class="no">no_unhashed_relocation</span><span class="p">,</span><span class="no">noborder</span><span class="p">,</span><span class="no">notail</span>
<span class="no">ext2_defaults</span><span class="o">=</span><span class="no">errors</span><span class="o">=</span><span class="no">remount</span><span class="o">-</span><span class="no">ro</span>
<span class="no">ext2_allow</span><span class="o">=</span><span class="no">errors</span><span class="o">=</span><span class="no">remount</span><span class="o">-</span><span class="no">ro</span>
<span class="no">ext3_defaults</span><span class="o">=</span><span class="no">errors</span><span class="o">=</span><span class="no">remount</span><span class="o">-</span><span class="no">ro</span>
<span class="no">ext3_allow</span><span class="o">=</span><span class="no">errors</span><span class="o">=</span><span class="no">remount</span><span class="o">-</span><span class="no">ro</span><span class="p">,</span><span class="no">commit</span>
<span class="no">ext4_defaults</span><span class="o">=</span><span class="no">errors</span><span class="o">=</span><span class="no">remount</span><span class="o">-</span><span class="no">ro</span>
<span class="no">ext4_allow</span><span class="o">=</span><span class="no">errors</span><span class="o">=</span><span class="no">remount</span><span class="o">-</span><span class="no">ro</span><span class="p">,</span><span class="no">commit</span></pre></td>
</tr>
</tbody>
</table>
</div>
<p>
</p>
<p>
Typically for each filesystem signature a pair of two sets are defined: <code class="literal">_allow</code> and <code class="literal">_defaults</code>.
The syntax of each record is <code class="literal">fs_signature[:fs_driver]_key=value1,value2,...</code> where <code class="literal">fs_signature</code> denotes the on-disk filesystem signature as detected by <code class="literal">udev/blkid</code>,
an optional <code class="literal">fs_driver</code> separated by the '<code class="literal">:</code>' character indicates the filesystem type (<span class="emphasis"><em>driver</em></span>) to use for the mount call and
the <code class="literal">key</code> is one of the <code class="literal">_allow</code>, <code class="literal">_defaults</code> or <code class="literal">_drivers</code> set of values.
In case the optional <code class="literal">fs_driver</code> part is not specified, it is expected that the name of the filesystem drive equals to filesystem signature, as usual.
</p>
<p>
The <code class="literal">_allow</code> set define mount options ever allowed and considered, the <code class="literal">_defaults</code> are the target options to use that are then (after further amendmends) passed to the mount command.
</p>
<p>
The <code class="literal">_defaults</code> always need to be a subset of <code class="literal">_allow</code>. The <code class="literal">_defaults</code> options are also merged with any extra options passed via the <a class="link" href="gdbus-org.freedesktop.UDisks2.Filesystem.html#gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount" title="The Mount() method">Mount()</a> method call.
</p>
<p>
Optionally, the <code class="literal">_drivers</code> set defines filesystem driver priorities for the particular filesystem signature to use for the actual mount call, from highest to lowest.
Only the <code class="literal">fs_driver</code> part of the <code class="literal">fs_signature[:fs_driver]_key</code> triplet should be specified here, separated by comma.
</p>
<p>
The <a class="link" href="gdbus-org.freedesktop.UDisks2.Filesystem.html#gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount" title="The Mount() method">Mount()</a> method call will then attempt to mount the filesystem using computed options defined for the particular filesystem driver separately.
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.
Distributors are suggested to tweak the priorities according to the supported filesystem drivers.
To take advantage of this functionality the <code class="literal">_drivers</code> 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.
</p>
<p>
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 <code class="literal">rw</code>, <code class="literal">ro</code>, etc.
Let's refer to them as <code class="literal"><span class="emphasis"><em>any</em></span></code> filesystem options for simplicity in the further text. The result of option set stacking, overrides and merging is referred to as <span class="emphasis"><em>(resulting) computed set of options</em></span>.
</p>
<p>
Apart from the final computed options UDisks always adds the following options due to security concerns: <code class="literal">nodev</code>, <code class="literal">nosuid</code>, <code class="literal">uhelper=udisks2</code> no matter if included in <code class="literal">_allow</code> or not. These are hardcoded and can't be changed.
</p>
<p>
Options that are not allowed in the computed <code class="literal">_allow</code> set will fail the mount operation with an error.
</p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.9"></a>Unprivileged mounts, UID and GID passing</h2></div></div></div>
<p>
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.
This is usually done by passing the <code class="literal">uid</code> and <code class="literal">gid</code> mount options that common filesystems honour. UDisks take the D-Bus method caller effective UID and finds its corresponding primary GID.
</p>
<p>
Also a <code class="literal">uhelper=udisks2</code> mount option is added automatically to indicate the umount command to use UDisks again for unmounting when called by an unprivileged user.
</p>
<p>
To allow flexibility in mount option naming, two special values are defined as placeholders for aforementioned IDs: <code class="literal">$UID</code> and <code class="literal">$GID</code>.
These are supposed to be defined as values for specific mount options (typically <code class="literal">uid</code> and <code class="literal">gid</code>) within the <code class="literal">_allow</code> set and are then replaced with numerical values in the late phase of mount option computation.
</p>
<p>
It's worth noting that there are few more options whose arguments are being replaced by computed values: <code class="literal">mode</code> and <code class="literal">dmode</code>.
These options are hardcoded at the moment and its values depend on the udev <code class="literal">UDISKS_FILESYSTEM_SHARED</code> attribute presence on the block device.
</p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.10"></a>Option set specifics</h2></div></div></div>
<p>
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.
</p>
<p>
As explained above any particular mount option either defined in the <code class="literal">_defaults</code> set or passed as an extra argument via the <a class="link" href="gdbus-org.freedesktop.UDisks2.Filesystem.html#gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount" title="The Mount() method">Mount()</a> method call need to be allowed by the <code class="literal">_allow</code> set of mount options.
There's however a difference in how the option is allowed and what arguments are valid.
</p>
<p>
When a considered option is defined with either of the <code class="literal">$UID</code> or <code class="literal">$GID</code> values within the <code class="literal">_allow</code> set (see previous chapter), special rules apply.
In case the value of a considered option is the <code class="literal">$UID</code>/<code class="literal">$GID</code> placeholder (as is the case of builtin set of options) or no value is specified at all (e.g. the <code class="literal">uid=</code> string),
the <a class="link" href="gdbus-org.freedesktop.UDisks2.Filesystem.html#gdbus-method-org-freedesktop-UDisks2-Filesystem.Mount" title="The Mount() method">Mount()</a> method caller UID or GID is automatically added.
In case a particular value is present (e.g. <code class="literal">uid=1001</code>) it is only allowed when the caller UID matches the option value.
</p>
<p>
In case a considered option is specified explicitly with a value within the <code class="literal">_allow</code> set no other checks are performed and this <code class="literal">option=value</code> pair is always allowed.
This even bypasses UID and GID checks, except of the <code class="literal">$UID</code> or <code class="literal">$GID</code> strings.
</p>
<p>
This permits various combinations of caller mount options such as <code class="literal">uid=$UID,uid=ignore</code> for UDF filesystem where the <code class="literal">uid=ignore</code> mount options is always allowed yet standard checks (<code class="literal">uid=$UID</code>) for numerical UID values are still preserved.
Similarly, certain numeric UID/GID values may be explicitly allowed this way, allowing non-privileged callers to use predefined IDs (e.g. <code class="literal">uid=1000,uid=1500,uid=ignore</code> within <code class="literal">_allow</code>).
This also allows to specify arbitrary values permitted, where each pair needs to be specified separately, i.e. <code class="literal">iocharset=utf8,iocharset=iso8859-1,iocharset=iso8859-2</code>.
</p>
<p>
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 <code class="literal">option</code> and <code class="literal">option=</code> (i.e. an empty value) in such definitions.
</p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.11"></a>The config file syntax</h2></div></div></div>
<p>
A sample config file showing rich syntax:
</p>
<pre class="programlisting">
[defaults]
# common options, applied to any filesystem, always merged with specific filesystem type options
defaults=ro
allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload
# specific filesystem type options
vfat_defaults=uid=$UID,gid=$GID,shortname=mixed,utf8=1,showexec,flush
vfat_allow=uid=$UID,gid=$GID,flush,utf8,shortname,umask,dmask,fmask,codepage,iocharset,usefree,showexec
ntfs_defaults=uid=$UID,gid=$GID,windows_names
ntfs_allow=uid=$UID,gid=$GID,umask,dmask,fmask,locale,norecover,ignore_case,windows_names
[/dev/disk/by-uuid/18afd8f0-0d86-4d96-8de0-5f92d2ee9800]
vfat_defaults=uid=$UID,gid=$GID,noexec
[/dev/disk/by-label/EFI]
vfat_defaults=noexec,umask=111,dmask=000
</pre>
<p>
</p>
<p>
The format of the configuration file is an INI-style key-value file parseable by <a class="ulink" href="https://developer.gnome.org/glib/stable/glib-Key-value-file-parser.html" target="_top"><span class="type">GKeyFile</span></a>.
The default location of the file unless specified otherwise during build time is <code class="filename">/etc/udisks2/mount_options.conf</code>. Sample config file is shipped along the source code.
</p>
<p>
The config file may contain multiple groups with a common <code class="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.
It's strongly encouraged to use stable block device identifiers (that is e.g. <code class="filename">/dev/disk/by-*</code>). No wildcards or glob expansion is performed, for fine-grained matching please use overrides through the custom udev rules.
This shouldn't be abused to weaken security requirements though, it's quite easy to fake storage identifiers, more so on removable media.
</p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.12"></a>udev rules overrides</h2></div></div></div>
<p>
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.
</p>
<p>
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.
The override mechanism and rules are no different from the config file level <code class="literal">[defaults]</code> group. There's just a slight syntactic difference to align with usual udev <code class="literal">ENV</code> naming conventions, consisting of the <code class="literal">UDISKS_MOUNT_OPTIONS_</code> key prefix.
</p>
<p>
Depending on your distribution specifics there are usually several paths designated for placing custom udev rules, with <code class="filename">/etc/udev/rules.d/</code> and <code class="filename">/lib/udev/rules.d</code> being the common ones. It's strongly recommended to make the rules run last, by the <code class="filename">99-</code> filename prefix.
</p>
<p>
Sample udev rules may look as follows:
</p>
<pre class="programlisting">
# This file contains custom mount options for udisks 2.x
#
# Skip if not a block device or if requested by other rules
#
SUBSYSTEM!="block", GOTO="udisks_mount_options_end"
ENV{DM_MULTIPATH_DEVICE_PATH}=="1", GOTO="udisks_mount_options_end"
ENV{DM_UDEV_DISABLE_OTHER_RULES_FLAG}=="?*", GOTO="udisks_mount_options_end"
# Additional mount options passed to udisksd to allow sysadmins to restrict mount to read-only or "noexec"
# for example:
#
# ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="ro,noexec"
# ENV{UDISKS_MOUNT_OPTIONS_ALLOW}="exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload"
#
# Use specific charset for FAT filesystems
#
# ENV{ID_FS_TYPE}=="vfat", \
# ENV{UDISKS_MOUNT_OPTIONS_VFAT_DEFAULTS}="uid=$UID,gid=$GID,shortname=mixed,utf8=0,iocharset=iso8859-15,showexec,flush"
#
# Mount all USB devices read-only
#
# SUBSYSTEMS=="usb", ENV{ID_FS_USAGE}=="filesystem", ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="ro"
LABEL="udisks_mount_options_end"
</pre>
<p>
</p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.13"></a>Levels of overrides</h2></div></div></div>
<p>
Levels from lower to higher:
</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">builtin options</li>
<li class="listitem">global config file (i.e. <code class="filename">/etc/udisks2/mount_options.conf</code>)</li>
<li class="listitem">udev rules</li>
</ul></div>
<p>
</p>
<p>
Higher level options always fully override lower levels.
</p>
<p>
While the builtin options are always present, upper levels are optional.
</p>
<p>
Each level may consist of a common group and block device specific groups.
</p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.14"></a>Rules computation</h2></div></div></div>
<p>
This is the most important part to understand as badly formulated options may lead to unforeseen consequences.
</p>
<p>
As a general rule, set of options from higher levels always fully replace (<span class="emphasis"><em>cover</em></span>, <span class="emphasis"><em>override</em></span>) options from lower levels.
This works on per-set basis, i.e. separately for each of the <code class="literal">_allow</code> and <code class="literal">_defaults</code> sets.
Please pay attention to allowance of the mount options overridden in the <code class="literal">_defaults</code> set at a given level without overriding the <code class="literal">_allow</code> set at the same place - lower levels may not allow all the options.
</p>
<p>
First, overrides are computed within each level. At a given level, block device specific options take higher priority over the common options (the <code class="code">[defaults]</code> group) and fully override them.
</p>
<p>
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.
</p>
<p>
The filesystem type specific options and common options (<code class="literal"><span class="emphasis"><em>any</em></span></code>) are computed separately across all levels per-set basis.
</p>
<p>
As a final step, when all sets are layered and computed onto a flat level, filesystem specific options and common options are merged together.
</p>
<p>
See the examples for further illustration.
</p>
</div>
<div class="simplesect">
<div class="titlepage"><div><div><h2 class="title" style="clear: both">
<a name="id-1.2.8.15"></a>Examples</h2></div></div></div>
<p>
</p>
<div class="example">
<a name="id-1.2.8.15.2.1"></a><p class="title"><b>Example 1. Disable <code class="literal">flush</code> on vfat and <code class="literal">windows_names</code> on ntfs</b></p>
<div class="example-contents">
<pre class="programlisting">
[defaults]
vfat_defaults=uid=$UID,gid=$GID,shortname=mixed,utf8=1,showexec
ntfs_defaults=uid=$UID,gid=$GID
</pre>
<div class="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.</div>
</div>
</div>
<p><br class="example-break">
</p>
<div class="example">
<a name="id-1.2.8.15.2.2"></a><p class="title"><b>Example 2. Force all mounts read only</b></p>
<div class="example-contents">
<pre class="programlisting">
[defaults]
defaults=ro
allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
</pre>
<div class="note">Note that this doesn't apply to fstab mounts where mount options are fully respected.</div>
</div>
</div>
<p><br class="example-break">
</p>
<div class="example">
<a name="id-1.2.8.15.2.3"></a><p class="title"><b>Example 3. Force all mounts read only except of my trusty USB drive</b></p>
<div class="example-contents">
<pre class="programlisting">
[defaults]
defaults=ro
allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
[/dev/disk/by-uuid/18afd8f0-0d86-4d96-8de0-5f92d2ee9800]
defaults=
allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload
</pre>
<div class="note">Note that this possesses a security risk as it's rather easy to fake commonly used identifiers like UUIDs, labels, etc.</div>
</div>
</div>
<p><br class="example-break">
</p>
<div class="example">
<a name="id-1.2.8.15.2.4"></a><p class="title"><b>Example 4. Much safer way of matching my trusty USB drive</b></p>
<div class="example-contents">
<pre class="programlisting">
[defaults]
defaults=ro
allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
</pre>
<pre class="programlisting">
SUBSYSTEM!="block", GOTO="udisks_mount_options_end"
ENV{DM_MULTIPATH_DEVICE_PATH}=="1", GOTO="udisks_mount_options_end"
ENV{DM_UDEV_DISABLE_OTHER_RULES_FLAG}=="?*", GOTO="udisks_mount_options_end"
ENV{ID_VENDOR}=="TrustyQualityInc", ENV{ID_MODEL}=="Unbreakable USB Stick", \
ENV{ID_SERIAL}=="360014055282611e2e7440198ca5d8ceb", \
ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="rw", \
ENV{UDISKS_MOUNT_OPTIONS_ALLOW}="exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload"
LABEL="udisks_mount_options_end"
</pre>
</div>
</div>
<p><br class="example-break">
</p>
<div class="example">
<a name="id-1.2.8.15.2.5"></a><p class="title"><b>Example 5. Allow fine-grained control over UIDs</b></p>
<div class="example-contents">
<pre class="programlisting">
[defaults]
vfat_allow=uid=1001,uid=1005,gid=$GID,flush,utf8,shortname,umask,dmask,fmask,codepage,iocharset,usefree,showexec
</pre>
<div class="note">Notice that the usual <code class="literal">uid=$UID</code> option is missing from the <code class="literal">vfat_allow</code> set and specific allowed UIDs are the only ones defined.
As the <code class="literal">vfat_defaults</code> set is not being overridden here and still carries the <code class="literal">uid=$UID</code> mount option that gets automatically replaced by caller effective UID, the computed option value must match any of the <code class="literal">vfat_allow</code> options,
thus the whole mount operation will be denied if the UIDs don't match.</div>
</div>
</div>
<p><br class="example-break">
</p>
<div class="example">
<a name="id-1.2.8.15.2.6"></a><p class="title"><b>Example 6. Multiple filesystem drivers for a common filesystem signature</b></p>
<div class="example-contents">
<table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
<tbody>
<tr>
<td class="listing_lines" align="right"><pre>1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></td>
<td class="listing_code"><pre class="programlisting"><span class="p">[</span><span class="n">defaults</span><span class="p">]</span>
<span class="cp"># the legacy ntfs kernel driver and the ntfs-3g fuse driver</span>
<span class="cp"># the usual case where the filesystem signature corresponds with the filesystem driver</span>
<span class="n">ntfs_defaults</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">windows_names</span>
<span class="n">ntfs_allow</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">umask</span><span class="p">,</span><span class="n">dmask</span><span class="p">,</span><span class="n">fmask</span><span class="p">,</span><span class="n">locale</span><span class="p">,</span><span class="n">norecover</span><span class="p">,</span><span class="n">ignore_case</span><span class="p">,</span><span class="n">windows_names</span><span class="p">,</span><span class="n">compression</span><span class="p">,</span><span class="n">nocompression</span><span class="p">,</span><span class="n">big_writes</span>
<span class="cp"># ntfs3 kernel driver</span>
<span class="cp"># different filesystem driver for a common filesystem signature</span>
<span class="nl">ntfs</span><span class="p">:</span><span class="n">ntfs3_defaults</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span>
<span class="nl">ntfs</span><span class="p">:</span><span class="n">ntfs3_allow</span><span class="o">=</span><span class="n">uid</span><span class="o">=</span><span class="n">$UID</span><span class="p">,</span><span class="n">gid</span><span class="o">=</span><span class="n">$GID</span><span class="p">,</span><span class="n">umask</span><span class="p">,</span><span class="n">dmask</span><span class="p">,</span><span class="n">fmask</span><span class="p">,</span><span class="n">iocharset</span><span class="p">,</span><span class="n">discard</span><span class="p">,</span><span class="n">nodiscard</span><span class="p">,</span><span class="n">sparse</span><span class="p">,</span><span class="n">nosparse</span><span class="p">,</span><span class="n">hidden</span><span class="p">,</span><span class="n">nohidden</span><span class="p">,</span><span class="n">sys_immutable</span><span class="p">,</span><span class="n">nosys_immutable</span><span class="p">,</span><span class="n">showmeta</span><span class="p">,</span><span class="n">noshowmeta</span><span class="p">,</span><span class="n">prealloc</span><span class="p">,</span><span class="n">noprealloc</span>
<span class="cp"># filesystem driver order for the specified filesystem signature</span>
<span class="cp"># required to actually use the extra definitions</span>
<span class="n">ntfs_drivers</span><span class="o">=</span><span class="n">ntfs3</span><span class="p">,</span><span class="n">ntfs</span></pre></td>
</tr>
</tbody>
</table>
</div>
</div>
<p><br class="example-break">
</p>
</div>
</div>
<div class="footer">
<hr>Generated by GTK-Doc V1.35.1</div>
</body>
</html>
|
