Debian Codegraph @

doc/html/mount_options.html

raw
1 <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
2 <html>
3 <head>
4 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
5 <title>Configurable mount options: UDisks Reference Manual</title>
6 <meta name="generator" content="DocBook XSL Stylesheets Vsnapshot">
7 <link rel="home" href="index.html" title="UDisks Reference Manual">
8 <link rel="up" href="overview.html" title="Part I. Manual pages and Overview">
9 <link rel="prev" href="udisks2_lsm.conf.5.html" title="udisks2_lsm.conf">
10 <link rel="next" href="ref-dbus.html" title="Part II. D-Bus API Reference">
11 <meta name="generator" content="GTK-Doc V1.35.1 (XML mode)">
12 <link rel="stylesheet" href="style.css" type="text/css">
13 </head>
14 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
15 <table class="navigation" id="top" width="100%" summary="Navigation header" cellpadding="2" cellspacing="5"><tr valign="middle">
16 <td width="100%" align="left" class="shortcuts"></td>
17 <td><a accesskey="h" href="index.html"><img src="home.png" width="16" height="16" border="0" alt="Home"></a></td>
18 <td><a accesskey="u" href="overview.html"><img src="up.png" width="16" height="16" border="0" alt="Up"></a></td>
19 <td><a accesskey="p" href="udisks2_lsm.conf.5.html"><img src="left.png" width="16" height="16" border="0" alt="Prev"></a></td>
20 <td><a accesskey="n" href="ref-dbus.html"><img src="right.png" width="16" height="16" border="0" alt="Next"></a></td>
21 </tr></table>
22 <div class="chapter">
23 <div class="titlepage"><div><div><h2 class="title">
24 <a name="mount_options"></a>Configurable mount options</h2></div></div></div>
25 <p>
26 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).
27 This selection has been made with focus on the primary project target: end users, consumers and workstations mostly working with removable media.
28 </p>
29 <p>
30 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.
31 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.
32 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.
33 </p>
34 <p>
35 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.
36 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.
37 These options however need to be subset of allowed mount options for the given filesystem type.
38 </p>
39 <p>
40 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.
41 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.
42 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.
43 </p>
44 <p>
45 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.
46 </p>
47 <div class="simplesect">
48 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
49 <a name="id-1.2.8.7"></a>Filesystem signature vs. filesystem driver</h2></div></div></div>
50 <p>
51 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.
52 </p>
53 <p>
54 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.
55 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.
56 </p>
57 </div>
58 <div class="simplesect">
59 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
60 <a name="id-1.2.8.8"></a>Basic definitions</h2></div></div></div>
61 <p>
62 For the reference this is what the builtin set of options looks like:
63
64 </p>
65 <div class="informalexample">
66 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
67 <tbody>
68 <tr>
69 <td class="listing_lines" align="right"><pre>1
70 2
71 3
72 4
73 5
74 6
75 7
76 8
77 9
78 10
79 11
80 12
81 13
82 14
83 15
84 16
85 17
86 18
87 19
88 20
89 21
90 22
91 23
92 24
93 25
94 26
95 27
96 28
97 29
98 30
99 31
100 32
101 33
102 34
103 35
104 36
105 37
106 38
107 39
108 40
109 41
110 42
111 43
112 44
113 45
114 46
115 47</pre></td>
116 <td class="listing_code"><pre class="programlisting"><span class="p">[</span><span class="n">defaults</span><span class="p">]</span>
117 <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>
118
119 <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>
120 <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>
121
122 <span class="cp"># common options for both the native kernel driver and exfat-fuse</span>
123 <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>
124 <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>
125
126 <span class="cp"># &#39;ntfs&#39; signature, definitions for the legacy ntfs kernel driver and the ntfs-3g fuse driver</span>
127 <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>
128 <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>
129
130 <span class="cp"># &#39;ntfs&#39; signature, the new &#39;ntfs3&#39; kernel driver</span>
131 <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>
132 <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>
133
134 <span class="cp"># define order of filesystem driver priorities for the actual mount call,</span>
135 <span class="cp"># required definition for non-matching driver names</span>
136 <span class="no">ntfs_drivers</span><span class="o">=</span><span class="no">ntfs3</span><span class="p">,</span><span class="no">ntfs</span>
137
138 <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>
139 <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>
140
141 <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>
142 <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>
143
144 <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>
145 <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>
146
147 <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>
148
149 <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>
150
151 <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>
152
153 <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>
154
155 <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>
156 <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>
157
158 <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>
159 <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>
160
161 <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>
162 <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>
163 </tr>
164 </tbody>
165 </table>
166 </div>
167
168 <p>
169 </p>
170 <p>
171 Typically for each filesystem signature a pair of two sets are defined: <code class="literal">_allow</code> and <code class="literal">_defaults</code>.
172 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>,
173 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
174 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.
175 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.
176 </p>
177 <p>
178 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.
179 </p>
180 <p>
181 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.
182 </p>
183 <p>
184 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.
185 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.
186 </p>
187 <p>
188 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.
189 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.
190 Distributors are suggested to tweak the priorities according to the supported filesystem drivers.
191 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.
192 </p>
193 <p>
194 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.
195 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>.
196 </p>
197 <p>
198 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.
199 </p>
200 <p>
201 Options that are not allowed in the computed <code class="literal">_allow</code> set will fail the mount operation with an error.
202 </p>
203 </div>
204 <div class="simplesect">
205 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
206 <a name="id-1.2.8.9"></a>Unprivileged mounts, UID and GID passing</h2></div></div></div>
207 <p>
208 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.
209 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.
210 </p>
211 <p>
212 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.
213 </p>
214 <p>
215 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>.
216 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.
217 </p>
218 <p>
219 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>.
220 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.
221 </p>
222 </div>
223 <div class="simplesect">
224 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
225 <a name="id-1.2.8.10"></a>Option set specifics</h2></div></div></div>
226 <p>
227 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.
228 </p>
229 <p>
230 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.
231 There's however a difference in how the option is allowed and what arguments are valid.
232 </p>
233 <p>
234 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.
235 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),
236 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.
237 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.
238 </p>
239 <p>
240 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.
241 This even bypasses UID and GID checks, except of the <code class="literal">$UID</code> or <code class="literal">$GID</code> strings.
242 </p>
243 <p>
244 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.
245 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>).
246 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>.
247 </p>
248 <p>
249 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.
250 </p>
251 </div>
252 <div class="simplesect">
253 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
254 <a name="id-1.2.8.11"></a>The config file syntax</h2></div></div></div>
255 <p>
256 A sample config file showing rich syntax:
257 </p>
258 <pre class="programlisting">
259 [defaults]
260 # common options, applied to any filesystem, always merged with specific filesystem type options
261 defaults=ro
262 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload
263
264 # specific filesystem type options
265 vfat_defaults=uid=$UID,gid=$GID,shortname=mixed,utf8=1,showexec,flush
266 vfat_allow=uid=$UID,gid=$GID,flush,utf8,shortname,umask,dmask,fmask,codepage,iocharset,usefree,showexec
267 ntfs_defaults=uid=$UID,gid=$GID,windows_names
268 ntfs_allow=uid=$UID,gid=$GID,umask,dmask,fmask,locale,norecover,ignore_case,windows_names
269
270 [/dev/disk/by-uuid/18afd8f0-0d86-4d96-8de0-5f92d2ee9800]
271 vfat_defaults=uid=$UID,gid=$GID,noexec
272
273 [/dev/disk/by-label/EFI]
274 vfat_defaults=noexec,umask=111,dmask=000
275 </pre>
276 <p>
277 </p>
278 <p>
279 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>.
280 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.
281 </p>
282 <p>
283 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.
284 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.
285 This shouldn't be abused to weaken security requirements though, it's quite easy to fake storage identifiers, more so on removable media.
286 </p>
287 </div>
288 <div class="simplesect">
289 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
290 <a name="id-1.2.8.12"></a>udev rules overrides</h2></div></div></div>
291 <p>
292 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.
293 </p>
294 <p>
295 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.
296 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.
297 </p>
298 <p>
299 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.
300 </p>
301 <p>
302 Sample udev rules may look as follows:
303 </p>
304 <pre class="programlisting">
305 # This file contains custom mount options for udisks 2.x
306 #
307
308 # Skip if not a block device or if requested by other rules
309 #
310 SUBSYSTEM!="block", GOTO="udisks_mount_options_end"
311 ENV{DM_MULTIPATH_DEVICE_PATH}=="1", GOTO="udisks_mount_options_end"
312 ENV{DM_UDEV_DISABLE_OTHER_RULES_FLAG}=="?*", GOTO="udisks_mount_options_end"
313
314
315 # Additional mount options passed to udisksd to allow sysadmins to restrict mount to read-only or "noexec"
316 # for example:
317 #
318 # ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="ro,noexec"
319 # ENV{UDISKS_MOUNT_OPTIONS_ALLOW}="exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload"
320
321 #
322 # Use specific charset for FAT filesystems
323 #
324 # ENV{ID_FS_TYPE}=="vfat", \
325 # ENV{UDISKS_MOUNT_OPTIONS_VFAT_DEFAULTS}="uid=$UID,gid=$GID,shortname=mixed,utf8=0,iocharset=iso8859-15,showexec,flush"
326
327 #
328 # Mount all USB devices read-only
329 #
330 # SUBSYSTEMS=="usb", ENV{ID_FS_USAGE}=="filesystem", ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="ro"
331
332 LABEL="udisks_mount_options_end"
333 </pre>
334 <p>
335 </p>
336 </div>
337 <div class="simplesect">
338 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
339 <a name="id-1.2.8.13"></a>Levels of overrides</h2></div></div></div>
340 <p>
341 Levels from lower to higher:
342 </p>
343 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
344 <li class="listitem">builtin options</li>
345 <li class="listitem">global config file (i.e. <code class="filename">/etc/udisks2/mount_options.conf</code>)</li>
346 <li class="listitem">udev rules</li>
347 </ul></div>
348 <p>
349 </p>
350 <p>
351 Higher level options always fully override lower levels.
352 </p>
353 <p>
354 While the builtin options are always present, upper levels are optional.
355 </p>
356 <p>
357 Each level may consist of a common group and block device specific groups.
358 </p>
359 </div>
360 <div class="simplesect">
361 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
362 <a name="id-1.2.8.14"></a>Rules computation</h2></div></div></div>
363 <p>
364 This is the most important part to understand as badly formulated options may lead to unforeseen consequences.
365 </p>
366 <p>
367 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.
368 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.
369 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.
370 </p>
371 <p>
372 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.
373 </p>
374 <p>
375 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.
376 </p>
377 <p>
378 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.
379 </p>
380 <p>
381 As a final step, when all sets are layered and computed onto a flat level, filesystem specific options and common options are merged together.
382 </p>
383 <p>
384 See the examples for further illustration.
385 </p>
386 </div>
387 <div class="simplesect">
388 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
389 <a name="id-1.2.8.15"></a>Examples</h2></div></div></div>
390 <p>
391 </p>
392 <div class="example">
393 <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>
394 <div class="example-contents">
395 <pre class="programlisting">
396 [defaults]
397 vfat_defaults=uid=$UID,gid=$GID,shortname=mixed,utf8=1,showexec
398 ntfs_defaults=uid=$UID,gid=$GID
399 </pre>
400 <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>
401 </div>
402 </div>
403 <p><br class="example-break">
404
405 </p>
406 <div class="example">
407 <a name="id-1.2.8.15.2.2"></a><p class="title"><b>Example 2. Force all mounts read only</b></p>
408 <div class="example-contents">
409 <pre class="programlisting">
410 [defaults]
411 defaults=ro
412 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
413 </pre>
414 <div class="note">Note that this doesn't apply to fstab mounts where mount options are fully respected.</div>
415 </div>
416 </div>
417 <p><br class="example-break">
418
419 </p>
420 <div class="example">
421 <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>
422 <div class="example-contents">
423 <pre class="programlisting">
424 [defaults]
425 defaults=ro
426 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
427
428 [/dev/disk/by-uuid/18afd8f0-0d86-4d96-8de0-5f92d2ee9800]
429 defaults=
430 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload
431 </pre>
432 <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>
433 </div>
434 </div>
435 <p><br class="example-break">
436
437 </p>
438 <div class="example">
439 <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>
440 <div class="example-contents">
441 <pre class="programlisting">
442 [defaults]
443 defaults=ro
444 allow=exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,sync,dirsync,noload
445 </pre>
446 <pre class="programlisting">
447 SUBSYSTEM!="block", GOTO="udisks_mount_options_end"
448 ENV{DM_MULTIPATH_DEVICE_PATH}=="1", GOTO="udisks_mount_options_end"
449 ENV{DM_UDEV_DISABLE_OTHER_RULES_FLAG}=="?*", GOTO="udisks_mount_options_end"
450
451 ENV{ID_VENDOR}=="TrustyQualityInc", ENV{ID_MODEL}=="Unbreakable USB Stick", \
452 ENV{ID_SERIAL}=="360014055282611e2e7440198ca5d8ceb", \
453 ENV{UDISKS_MOUNT_OPTIONS_DEFAULTS}="rw", \
454 ENV{UDISKS_MOUNT_OPTIONS_ALLOW}="exec,noexec,nodev,nosuid,atime,noatime,nodiratime,ro,rw,sync,dirsync,noload"
455
456 LABEL="udisks_mount_options_end"
457 </pre>
458 </div>
459 </div>
460 <p><br class="example-break">
461
462 </p>
463 <div class="example">
464 <a name="id-1.2.8.15.2.5"></a><p class="title"><b>Example 5. Allow fine-grained control over UIDs</b></p>
465 <div class="example-contents">
466 <pre class="programlisting">
467 [defaults]
468 vfat_allow=uid=1001,uid=1005,gid=$GID,flush,utf8,shortname,umask,dmask,fmask,codepage,iocharset,usefree,showexec
469 </pre>
470 <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.
471 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,
472 thus the whole mount operation will be denied if the UIDs don't match.</div>
473 </div>
474 </div>
475 <p><br class="example-break">
476
477 </p>
478 <div class="example">
479 <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>
480 <div class="example-contents">
481 <table class="listing_frame" border="0" cellpadding="0" cellspacing="0">
482 <tbody>
483 <tr>
484 <td class="listing_lines" align="right"><pre>1
485 2
486 3
487 4
488 5
489 6
490 7
491 8
492 9
493 10
494 11
495 12
496 13
497 14</pre></td>
498 <td class="listing_code"><pre class="programlisting"><span class="p">[</span><span class="n">defaults</span><span class="p">]</span>
499 <span class="cp"># the legacy ntfs kernel driver and the ntfs-3g fuse driver</span>
500 <span class="cp"># the usual case where the filesystem signature corresponds with the filesystem driver</span>
501 <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>
502 <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>
503
504 <span class="cp"># ntfs3 kernel driver</span>
505 <span class="cp"># different filesystem driver for a common filesystem signature</span>
506 <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>
507 <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>
508
509 <span class="cp"># filesystem driver order for the specified filesystem signature</span>
510 <span class="cp"># required to actually use the extra definitions</span>
511 <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>
512 </tr>
513 </tbody>
514 </table>
515 </div>
516
517 </div>
518 <p><br class="example-break">
519
520 </p>
521 </div>
522 </div>
523 <div class="footer">
524 <hr>Generated by GTK-Doc V1.35.1</div>
525 </body>
526 </html>