]>
Commit | Line | Data |
---|---|---|
6a7e2bbe SH |
1 | QEMU virtio-fs shared file system daemon |
2 | ======================================== | |
3 | ||
4 | Synopsis | |
5 | -------- | |
6 | ||
7 | **virtiofsd** [*OPTIONS*] | |
8 | ||
9 | Description | |
10 | ----------- | |
11 | ||
12 | Share a host directory tree with a guest through a virtio-fs device. This | |
13 | program is a vhost-user backend that implements the virtio-fs device. Each | |
14 | virtio-fs device instance requires its own virtiofsd process. | |
15 | ||
16 | This program is designed to work with QEMU's ``--device vhost-user-fs-pci`` | |
17 | but should work with any virtual machine monitor (VMM) that supports | |
18 | vhost-user. See the Examples section below. | |
19 | ||
06844584 SH |
20 | This program must be run as the root user. The program drops privileges where |
21 | possible during startup although it must be able to create and access files | |
22 | with any uid/gid: | |
23 | ||
24 | * The ability to invoke syscalls is limited using seccomp(2). | |
25 | * Linux capabilities(7) are dropped. | |
26 | ||
27 | In "namespace" sandbox mode the program switches into a new file system | |
28 | namespace and invokes pivot_root(2) to make the shared directory tree its root. | |
29 | A new pid and net namespace is also created to isolate the process. | |
30 | ||
31 | In "chroot" sandbox mode the program invokes chroot(2) to make the shared | |
32 | directory tree its root. This mode is intended for container environments where | |
33 | the container runtime has already set up the namespaces and the program does | |
34 | not have permission to create namespaces itself. | |
35 | ||
36 | Both sandbox modes prevent "file system escapes" due to symlinks and other file | |
37 | system objects that might lead to files outside the shared directory. | |
6a7e2bbe SH |
38 | |
39 | Options | |
40 | ------- | |
41 | ||
42 | .. program:: virtiofsd | |
43 | ||
44 | .. option:: -h, --help | |
45 | ||
46 | Print help. | |
47 | ||
48 | .. option:: -V, --version | |
49 | ||
50 | Print version. | |
51 | ||
52 | .. option:: -d | |
53 | ||
54 | Enable debug output. | |
55 | ||
56 | .. option:: --syslog | |
57 | ||
58 | Print log messages to syslog instead of stderr. | |
59 | ||
60 | .. option:: -o OPTION | |
61 | ||
62 | * debug - | |
63 | Enable debug output. | |
64 | ||
65 | * flock|no_flock - | |
66 | Enable/disable flock. The default is ``no_flock``. | |
67 | ||
3005c099 DDAG |
68 | * modcaps=CAPLIST |
69 | Modify the list of capabilities allowed; CAPLIST is a colon separated | |
70 | list of capabilities, each preceded by either + or -, e.g. | |
71 | ''+sys_admin:-chown''. | |
72 | ||
6a7e2bbe SH |
73 | * log_level=LEVEL - |
74 | Print only log messages matching LEVEL or more severe. LEVEL is one of | |
75 | ``err``, ``warn``, ``info``, or ``debug``. The default is ``info``. | |
76 | ||
6a7e2bbe | 77 | * posix_lock|no_posix_lock - |
88fc1079 | 78 | Enable/disable remote POSIX locks. The default is ``no_posix_lock``. |
6a7e2bbe SH |
79 | |
80 | * readdirplus|no_readdirplus - | |
81 | Enable/disable readdirplus. The default is ``readdirplus``. | |
82 | ||
06844584 SH |
83 | * sandbox=namespace|chroot - |
84 | Sandbox mode: | |
85 | - namespace: Create mount, pid, and net namespaces and pivot_root(2) into | |
86 | the shared directory. | |
87 | - chroot: chroot(2) into shared directory (use in containers). | |
88 | The default is "namespace". | |
89 | ||
6a7e2bbe SH |
90 | * source=PATH - |
91 | Share host directory tree located at PATH. This option is required. | |
92 | ||
93 | * timeout=TIMEOUT - | |
94 | I/O timeout in seconds. The default depends on cache= option. | |
95 | ||
96 | * writeback|no_writeback - | |
76ca4b58 | 97 | Enable/disable writeback cache. The cache allows the FUSE client to buffer |
6a7e2bbe SH |
98 | and merge write requests. The default is ``no_writeback``. |
99 | ||
100 | * xattr|no_xattr - | |
101 | Enable/disable extended attributes (xattr) on files and directories. The | |
102 | default is ``no_xattr``. | |
103 | ||
104 | .. option:: --socket-path=PATH | |
105 | ||
106 | Listen on vhost-user UNIX domain socket at PATH. | |
107 | ||
f6698f2b AB |
108 | .. option:: --socket-group=GROUP |
109 | ||
110 | Set the vhost-user UNIX domain socket gid to GROUP. | |
111 | ||
6a7e2bbe SH |
112 | .. option:: --fd=FDNUM |
113 | ||
114 | Accept connections from vhost-user UNIX domain socket file descriptor FDNUM. | |
115 | The file descriptor must already be listening for connections. | |
116 | ||
117 | .. option:: --thread-pool-size=NUM | |
118 | ||
119 | Restrict the number of worker threads per request queue to NUM. The default | |
120 | is 64. | |
121 | ||
122 | .. option:: --cache=none|auto|always | |
123 | ||
124 | Select the desired trade-off between coherency and performance. ``none`` | |
125 | forbids the FUSE client from caching to achieve best coherency at the cost of | |
126 | performance. ``auto`` acts similar to NFS with a 1 second metadata cache | |
127 | timeout. ``always`` sets a long cache lifetime at the expense of coherency. | |
f1303afe | 128 | The default is ``auto``. |
6a7e2bbe | 129 | |
6084633d DDAG |
130 | xattr-mapping |
131 | ------------- | |
132 | ||
133 | By default the name of xattr's used by the client are passed through to the server | |
134 | file system. This can be a problem where either those xattr names are used | |
135 | by something on the server (e.g. selinux client/server confusion) or if the | |
136 | virtiofsd is running in a container with restricted privileges where it cannot | |
137 | access some attributes. | |
138 | ||
139 | A mapping of xattr names can be made using -o xattrmap=mapping where the ``mapping`` | |
140 | string consists of a series of rules. | |
141 | ||
142 | The first matching rule terminates the mapping. | |
143 | The set of rules must include a terminating rule to match any remaining attributes | |
144 | at the end. | |
145 | ||
146 | Each rule consists of a number of fields separated with a separator that is the | |
147 | first non-white space character in the rule. This separator must then be used | |
148 | for the whole rule. | |
149 | White space may be added before and after each rule. | |
1d84a021 | 150 | |
6084633d DDAG |
151 | Using ':' as the separator a rule is of the form: |
152 | ||
153 | ``:type:scope:key:prepend:`` | |
154 | ||
155 | **scope** is: | |
156 | ||
157 | - 'client' - match 'key' against a xattr name from the client for | |
158 | setxattr/getxattr/removexattr | |
159 | - 'server' - match 'prepend' against a xattr name from the server | |
160 | for listxattr | |
161 | - 'all' - can be used to make a single rule where both the server | |
162 | and client matches are triggered. | |
163 | ||
164 | **type** is one of: | |
165 | ||
166 | - 'prefix' - is designed to prepend and strip a prefix; the modified | |
167 | attributes then being passed on to the client/server. | |
168 | ||
169 | - 'ok' - Causes the rule set to be terminated when a match is found | |
170 | while allowing matching xattr's through unchanged. | |
171 | It is intended both as a way of explicitly terminating | |
172 | the list of rules, and to allow some xattr's to skip following rules. | |
173 | ||
174 | - 'bad' - If a client tries to use a name matching 'key' it's | |
175 | denied using EPERM; when the server passes an attribute | |
176 | name matching 'prepend' it's hidden. In many ways it's use is very like | |
177 | 'ok' as either an explict terminator or for special handling of certain | |
178 | patterns. | |
179 | ||
180 | **key** is a string tested as a prefix on an attribute name originating | |
181 | on the client. It maybe empty in which case a 'client' rule | |
182 | will always match on client names. | |
183 | ||
184 | **prepend** is a string tested as a prefix on an attribute name originating | |
185 | on the server, and used as a new prefix. It may be empty | |
186 | in which case a 'server' rule will always match on all names from | |
187 | the server. | |
188 | ||
189 | e.g.: | |
190 | ||
191 | ``:prefix:client:trusted.:user.virtiofs.:`` | |
192 | ||
193 | will match 'trusted.' attributes in client calls and prefix them before | |
194 | passing them to the server. | |
195 | ||
196 | ``:prefix:server::user.virtiofs.:`` | |
197 | ||
198 | will strip 'user.virtiofs.' from all server replies. | |
199 | ||
200 | ``:prefix:all:trusted.:user.virtiofs.:`` | |
201 | ||
202 | combines the previous two cases into a single rule. | |
203 | ||
204 | ``:ok:client:user.::`` | |
205 | ||
206 | will allow get/set xattr for 'user.' xattr's and ignore | |
207 | following rules. | |
208 | ||
209 | ``:ok:server::security.:`` | |
210 | ||
211 | will pass 'securty.' xattr's in listxattr from the server | |
212 | and ignore following rules. | |
213 | ||
214 | ``:ok:all:::`` | |
215 | ||
216 | will terminate the rule search passing any remaining attributes | |
217 | in both directions. | |
218 | ||
219 | ``:bad:server::security.:`` | |
220 | ||
221 | would hide 'security.' xattr's in listxattr from the server. | |
222 | ||
1d84a021 DDAG |
223 | A simpler 'map' type provides a shorter syntax for the common case: |
224 | ||
225 | ``:map:key:prepend:`` | |
226 | ||
227 | The 'map' type adds a number of separate rules to add **prepend** as a prefix | |
228 | to the matched **key** (or all attributes if **key** is empty). | |
229 | There may be at most one 'map' rule and it must be the last rule in the set. | |
230 | ||
491bfaea DDAG |
231 | xattr-mapping Examples |
232 | ---------------------- | |
233 | ||
234 | 1) Prefix all attributes with 'user.virtiofs.' | |
235 | ||
236 | :: | |
237 | ||
238 | -o xattrmap=":prefix:all::user.virtiofs.::bad:all:::" | |
239 | ||
240 | ||
241 | This uses two rules, using : as the field separator; | |
242 | the first rule prefixes and strips 'user.virtiofs.', | |
243 | the second rule hides any non-prefixed attributes that | |
244 | the host set. | |
245 | ||
1d84a021 DDAG |
246 | This is equivalent to the 'map' rule: |
247 | ||
248 | :: | |
249 | -o xattrmap=":map::user.virtiofs.:" | |
250 | ||
491bfaea DDAG |
251 | 2) Prefix 'trusted.' attributes, allow others through |
252 | ||
253 | :: | |
254 | ||
255 | "/prefix/all/trusted./user.virtiofs./ | |
256 | /bad/server//trusted./ | |
257 | /bad/client/user.virtiofs.// | |
258 | /ok/all///" | |
259 | ||
260 | ||
261 | Here there are four rules, using / as the field | |
262 | separator, and also demonstrating that new lines can | |
263 | be included between rules. | |
264 | The first rule is the prefixing of 'trusted.' and | |
265 | stripping of 'user.virtiofs.'. | |
266 | The second rule hides unprefixed 'trusted.' attributes | |
267 | on the host. | |
268 | The third rule stops a guest from explicitly setting | |
269 | the 'user.virtiofs.' path directly. | |
270 | Finally, the fourth rule lets all remaining attributes | |
271 | through. | |
272 | ||
1d84a021 DDAG |
273 | This is equivalent to the 'map' rule: |
274 | ||
275 | :: | |
276 | -o xattrmap="/map/trusted./user.virtiofs./" | |
277 | ||
491bfaea DDAG |
278 | 3) Hide 'security.' attributes, and allow everything else |
279 | ||
280 | :: | |
281 | ||
282 | "/bad/all/security./security./ | |
283 | /ok/all///' | |
284 | ||
285 | The first rule combines what could be separate client and server | |
286 | rules into a single 'all' rule, matching 'security.' in either | |
287 | client arguments or lists returned from the host. This stops | |
288 | the client seeing any 'security.' attributes on the server and | |
289 | stops it setting any. | |
290 | ||
6a7e2bbe SH |
291 | Examples |
292 | -------- | |
293 | ||
294 | Export ``/var/lib/fs/vm001/`` on vhost-user UNIX domain socket | |
295 | ``/var/run/vm001-vhost-fs.sock``: | |
296 | ||
297 | :: | |
298 | ||
299 | host# virtiofsd --socket-path=/var/run/vm001-vhost-fs.sock -o source=/var/lib/fs/vm001 | |
300 | host# qemu-system-x86_64 \ | |
301 | -chardev socket,id=char0,path=/var/run/vm001-vhost-fs.sock \ | |
302 | -device vhost-user-fs-pci,chardev=char0,tag=myfs \ | |
303 | -object memory-backend-memfd,id=mem,size=4G,share=on \ | |
304 | -numa node,memdev=mem \ | |
305 | ... | |
306 | guest# mount -t virtiofs myfs /mnt |