File: mount_fusefs.8

package info (click to toggle)
fuse4bsd 0.3.9~pre1.20080208-4
  • links: PTS
  • area: main
  • in suites: wheezy
  • size: 832 kB
  • sloc: ansic: 6,827; ruby: 258; makefile: 154; sh: 71; awk: 37
file content (373 lines) | stat: -rw-r--r-- 11,469 bytes parent folder | download | duplicates (2)
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
.\" Copyright (c) 1980, 1989, 1991, 1993
.\"	The Regents of the University of California.
.\" Copyright (c) 2005, 2006 Csaba Henk
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.Dd January 13, 2006
.Dt MOUNT_FUSEFS 8
.Os
.Sh NAME
.Nm mount_fusefs
.Nd mount a Fuse file system daemon
.Sh SYNOPSIS
.Nm
.Op Fl A
.Op Fl S
.Op Fl v
.Op Fl D Ar fuse_daemon
.Op Fl O Ar daemon_opts
.Op Fl s Ar special
.Op Fl m Ar node
.Op Fl h
.Op Fl V
.Op Fl o Ar option ...
.Ar special node
.Op Ar fuse_daemon ...
.Sh DESCRIPTION
The most basic way of usage is as follows: before calling
.Nm ,
one starts a fuse daemon on the given
.Ar special
(in practice, the daemon gets one automatically, which can then be indentified
via
.Xr fstat 1 ) ,
and that special file can then be mounted by
.Nm .
.Pp
However, the procedure of spawning a daemon can be automated so that it's
also performed by
.Nm .
If the command invoking a given
.Ar fuse_daemon
is appended to the list of arguments,
.Nm
will call then
.Ar fuse_daemon
via that command, in a way that
.Ar fuse_daemon
will be instructed to attach itself to
.Ar special .
From that on mounting goes as in the simple case. (See also
.Sx DAEMON MOUNTS . )
.Pp
The
.Ar special
argument can be utilized by
.Nm
in the following ways:
.Bl -bullet -offset indent
.It
Basicly, it will be treated as the path of the special file to mount.
.It
However, if
.Pa auto
is passed as
.Ar special ,
then
.Nm
will look for a suitable free fuse device by itself.
.It
Moreover, if
.Ar special
is an integer, then it will be interpreted as the number
of the file descriptor of an already open fuse device
(used when the Fuse library invokes
.Nm ,
cf.
.Sx DAEMON MOUNTS ) .
.El
.Pp
The options are as follows:
.Bl -tag -width indent
.It Fl A , Ic --reject-allow_other
Prohibit the
.Cm allow_other
mount flag. Intended for to be used in scripts and the
.Xr sudoers 5
file.
.It Fl S , Ic --safe
Run in safe mode, that is, reject invoking a filesystem daemon.
.It Fl v
Be verbose.
.It Fl D, Ic --daemon Ar daemon
Call the specified
.Ar daemon .
.It Fl O, Ic --daemon_opts Ar opts
Add
.Ar opts
to the daemon's command line.
.It Fl s, Ic --special Ar special
Use
.Ar special
as special.
.It Fl m, Ic --mountpath Ar node
Mount on
.Ar node .
.It Fl h, Ic --help
Show help.
.It Fl V, Ic --version
Show version information.
.It Fl o
Mount options are specified via
.Fl o .
The following options are available (and also their negated versions,
by prefixing them with
.Dq no ) :
.Bl -tag -width indent
.It Cm default_permissions
Enable traditional (file mode based) permission checking in kernel.
.It Cm allow_other 
Do not apply
.Sx STRICT ACCESS POLICY .
Only root can use this option.
.It Cm max_read Ns = Ns Ar n
Limit size of read requests with
.Ar n .
.It Cm private
Refuse shared mounting of the daemon. This is the default behaviour,
to allow sharing, use expicitly
.Fl o Cm noprivate .
.It Cm neglect_shares
Don't refuse unmounting if there are secondary mounts. 
.It Cm push_symlinks_in
Prefix absolute symlinks with mountpoint.
.El
.Pp
.El
.Pp
Besides the above mount options, there is a set of pseudo-mount options which
are supported by the Fuse library. One can list these by passing
.Fl h
to a Fuse daemon. Most of these options have effect only on the behaviour of
the daemon (that is, their scope is limited to userspace). However, 
there are some which do require in-kernel support.
Currently the following ones are supported by the kernel:
.Bl -tag -width indent
.It Cm direct_io
Bypass the buffer cache system.
.It Cm kernel_cache
By default, cached buffers of a given file are flushed at each
.Xr open 2 .
This option disables this behaviour.
.El
.Sh DAEMON MOUNTS
Usually users don't need to use
.Nm
directly, as the Fuse library enables Fuse daemons to invoke
.Nm
by themselves. That is,
.Pp
.Dl fuse_daemon mountpoint
.Pp
has the same effect as
.Pp
.Dl mount_fusefs auto mountpoint fuse_daemon
.Pp
This is the recommended way of usage, unless you want to go beyond basic usage
(eg, run daemon on a low privilege level, but mount it as root).
.Sh STRICT ACCESS POLICY
The strict access policy for Fuse filesystems lets one to use the filesystem
only if the filesystem daemon has the same credentials (uid, real uid, gid,
real gid) as the user.
.Pp
This is applied for Fuse mounts by default, and only root can mount without
the strict access policy (cf. the
.Cm allow_other
mount option).
.Pp
The reason is to shield users from the daemon
.Dq spying
on their I/O activities.
.Pp
Users might opt for willingly relax strict access policy (as far they
are concerned) by doing their own secondary mount (cf.
.Sx SHARED MOUNTS ) .
.Sh SHARED MOUNTS
A Fuse daemon can be shared, ie. mounted multiple times.
When doing the first (primary) mount, the spawner and the mounter of the daemon
must have the same uid, or the mounter should be the superuser.
.Pp
After the primary mount is in place, secondary mounts can be done by anyone
(unless this feature is disabled by
.Cm private ) .
The behaviour of a secondary mount is analogous to that of symbolic
links: they redirect all filesystem operations to the primary mount.
.Pp
Doing a secondary mount is like signing an agreement: by this action, the mounter
agrees that the Fuse daemon can trace her I/O activities. From that on, she is not
banned from using the filesystem (either via her own mount or via the primary mount),
regardless whether
.Cm allow_other
is used or not.
.Pp
The device name of a secondary mount is the device name of the corresponding primary
mount, followed by a '#' character and the index of the secondary mount, like
.Pa /dev/fuse0#3 .
.Sh SECURITY
System administratos might want to use a custom mount policy (ie., one going beyond the
.Va vfs.usermount
sysctl). The primary tool for such purposes is
.Xr sudo 8 .
However, given that
.Nm
is capable of invoking an arbitrary program, one must be careful about this.
.Nm
is designed in a way such that it makes that easy. For this purpose,
there are options which disable certain risky features (cf.
.Fl S
and
.Fl A ) ,
and command line parsing is done in a flexible way: mixing options and
non-options allowed, but processing them stops at the third non-option argument
(after the first two has been utilized as device and mountpoint). The rest of
the command line specifies the daemon and its arguments. (Alternatively, the
daemon, the special and the mount path can be specified using the respective
options.) Note that
.Nm
ignores the environment variable
.Ev POSIXLY_CORRECT
and always behaves as described.
.Pp
In general, to be as scripting /
.Xr sudoers 5
friendly as possible, no information has a fixed
position in the command line, but once a given piece of information is
provided, subsequent arguments/options cannot override it (maybe with the
exception of some non-critical ones).
.Sh ENVIRONMENT
.Bl -tag -width ".Ev MOUNT_FUSEFS_SAFE"
.It Ev MOUNT_FUSEFS_SAFE
Setting this has the same effect as the
.Fl S
option.
.It Ev MOUNT_FUSEFS_VERBOSE
Setting this has the same effect as the
.Fl v
option.
.It Ev MOUNT_FUSEFS_IGNORE_UNKNOWN
If this is set,
.Nm
will ignore uknown mount options.
.It Ev MOUNT_FUSEFS_CALL_BY_LIB
Adjust behaviour to the needs of the FUSE library. Currently it has effect
on help output.
.El
.Pp
Although the following variables don't have effect on
.Nm
itself, they affect the behaviour of fuse daemons:
.Bl -tag -width ".Ev FUSE_DEV_NAME"
.It Ev FUSE_DEV_NAME
Device to get attached to. If not set, the multiplexer path
.Ar /dev/fuse
is used.
.It Ev FUSE_DEV_FD
File desciptor of an opened Fuse device to use. Overrides
.Ev FUSE_DEV_NAME .
.It Ev FUSE_NO_MOUNT
If this is set, the library won't attempt to mount the filesystem, even
if a mountpoint argument is supplied.
.El
.Sh FILES
.Bl -tag -width /dev/fuseN
.It Pa /dev/fuseN
Fuse devices by which the kernel and Fuse daemons can communicate.
.It Pa /dev/fuse
The multiplexer path. An
.Xr open 2
performed on it automatically gets passed to a free Fuse device by the kernel (which might be
just created for this puprose).
.El
.Sh EXAMPLES
Mounting the example filesystem of the Fuse distribution (from its directory): either
.Pp
.Dl ./fusexmp /mnt/fuse
.Pp
or
.Pp
.Dl mount_fusefs auto /mnt/fuse ./fusexmp
.Pp
Doing the same in two steps, using
.Pa /dev/fuse0 :
.Pp
.Dl FUSE_DEV_NAME=/dev/fuse0 ./fusexmp &&
.Dl mount_fusefs /dev/fuse0 /mnt/fuse
.Pp
A script wrapper for fusexmp which ensures that
.Nm 
doesn't call any external utility and also provides a hacky 
(non race-free) automatic device selection:
.Pp
.Dl #!/bin/sh -e
.Pp
.Dl n=`ls  /dev/fuse* | awk 'END{ print FNR }'`
.Dl FUSE_DEV_NAME=/dev/fuse$n fusexmp
.Dl mount_fusefs -S /dev/fuse$n /mnt/fuse \(lq$@\(rq
.Pp
A better (race-free) script wrapper:
.Pp
.Dl #!/bin/sh -e
.Pp
.Dl exec 3<>/dev/fuse
.Dl FUSE_DEV_FD=3 fusexmp
.Dl mount_fusefs -S 3 /mnt/fuse \(lq$@\(rq
.Sh SEE ALSO
.Xr fstat 1 ,
.Xr mount 8 ,
.Xr umount 8 ,
.Xr sudo 8
.Sh CAVEATS
Secondary mounts are to be unmounted via their device name. If they attempted to be unmounted via
their filesystem root path, the unmount request will be forwarded to the primary mount path.
In general, unmounting by device name is less error-prone than by mount path
(although the latter will also work under normal circumstances).
.Pp
If the daemon is specified via the
.Fl D
and
.Fl O
options, it will be invoked via
.Xr system 3 ,
and the daemon's command line will be also appended a
.Dq &
sygill, so that we don't have to wait for its termination. That is, you'd better
use a simple command line when invoking the daemon via these options.
.Sh HISTORY
.Nm
appears as the part of the FreeBSD implementation of the Fuse userspace filesystem
framework (see http://fuse.sourceforge.net). This user interface is FreeBSD specific.
.Sh BUGS
.Ar special
is treated as a multiplexer if and only if it's literally the same as
.Pa auto
or
.Pa /dev/fuse .
Other paths which are equivalent with
.Pa /dev/fuse
(eg.,
.Pa /../dev/fuse )
are not.