Attachment #174567 for bug #212513




.\"
.\" $FreeBSD$
.\"
.Dd September 9, 2016
.Dt MOUNT_FUSEFS 8
.Os
.Sh NAME

.Sh DESCRIPTION
Basic usage is to start a fuse daemon on the given
.Ar special
file.
In practice, the daemon is assigned a
.Ar special
file automatically, which can then be indentified via
.Xr fstat 1 .

.Nm
will call the
.Ar fuse_daemon
via that command.
In that way the
.Ar fuse_daemon
will be instructed to attach itself to
.Ar special .

.It Fl A , Ic --reject-allow_other
Prohibit the
.Cm allow_other
mount flag.
Intended for use in scripts and the
.Xr sudoers 5
file.
.It Fl S , Ic --safe
Run in safe mode (i.e reject invoking a filesystem daemon)
.It Fl v
Be verbose
.It Fl D, Ic --daemon Ar daemon

Limit size of read requests to
.Ar n
.It Cm private
Refuse shared mounting of the daemon.
This is the default behaviour, to allow sharing, expicitly use
.Fl o Cm noprivate
.It Cm neglect_shares
Do not refuse unmounting if there are secondary mounts

.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 options supported by the kernel are:
.Bl -tag -width indent
.It Cm direct_io

real gid) as the user.
.Pp
This is applied for Fuse mounts by default and only root can mount without
the strict access policy (i.e the
.Cm allow_other
mount option).
.Pp

are concerned) by doing their own secondary mount (See
.Sx SHARED MOUNTS ) .
.Sh SHARED MOUNTS
A Fuse daemon can be shared (i.e 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

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 then 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; e.g
.Pa /dev/fuse0#3 .
.Sh SECURITY
System administrators 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 when doing this.
.Nm
is designed in a way such that it makes that easy.
For this purpose, there are options which disable certain risky features (i.e
.Fl S
and
.Fl A ) ,

.Nm
will ignore uknown mount options.
.It Ev MOUNT_FUSEFS_CALL_BY_LIB
Adjust behaviour to the needs of the FUSE library.
Currently it effects help output.
.El
.Pp
Although the following variables do not have any effect on

itself, they affect the behaviour of fuse daemons:
.Bl -tag -width ".Ev FUSE_DEV_NAME"
.It Ev FUSE_DEV_NAME
Device to attach.
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 set, the library will not attempt to mount the filesystem, even

.It Pa /dev/fuse
Fuse device with which the kernel and Fuse daemons can communicate.
.It Pa /dev/fuse
The multiplexer path.
An
.Xr open 2
performed on it automatically is passed to a free Fuse device by the kernel
(which might be created just for this puprose).

.Xr umount 8
.Sh HISTORY
.Nm
appeared in
.Fx 10.0
as the part of the
.Fx
implementation of the Fuse userspace filesystem
framework (see http://fuse.sourceforge.net).
.Sh CAVEATS
This user interface is
.Fx
specific.
Secondary mounts should be unmounted via their device name.
If an attempt is made to be unmount them 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

Return to bug 212513

Lines 29-35 Link Here

(-)sbin/mount_fusefs/mount_fusefs.8 (-30 / +46 lines)
29	.\"	29	.\"
30	.\" $FreeBSD$	30	.\" $FreeBSD$
31	.\"	31	.\"
32	.Dd October 11, 2012	32	.Dd September 9, 2016
33	.Dt MOUNT_FUSEFS 8	33	.Dt MOUNT_FUSEFS 8
34	.Os	34	.Os
35	.Sh NAME	35	.Sh NAME
Lines 52-58 Link Here
52	.Sh DESCRIPTION	52	.Sh DESCRIPTION
53	Basic usage is to start a fuse daemon on the given	53	Basic usage is to start a fuse daemon on the given
54	.Ar special	54	.Ar special
55	file. In practice, the daemon is assigned a	55	file.
		56	In practice, the daemon is assigned a
56	.Ar special	57	.Ar special
57	file automatically, which can then be indentified via	58	file automatically, which can then be indentified via
58	.Xr fstat 1 .	59	.Xr fstat 1 .
Lines 68-74 Link Here
68	.Nm	69	.Nm
69	will call the	70	will call the
70	.Ar fuse_daemon	71	.Ar fuse_daemon
71	via that command. In that way the	72	via that command.
		73	In that way the
72	.Ar fuse_daemon	74	.Ar fuse_daemon
73	will be instructed to attach itself to	75	will be instructed to attach itself to
74	.Ar special .	76	.Ar special .
Lines 101-111 Link Here
101	.It Fl A , Ic --reject-allow_other	103	.It Fl A , Ic --reject-allow_other
102	Prohibit the	104	Prohibit the
103	.Cm allow_other	105	.Cm allow_other
104	mount flag. Intended for use in scripts and the	106	mount flag.
		107	Intended for use in scripts and the
105	.Xr sudoers 5	108	.Xr sudoers 5
106	file.	109	file.
107	.It Fl S , Ic --safe	110	.It Fl S , Ic --safe
108	Run in safe mode (i.e. reject invoking a filesystem daemon)	111	Run in safe mode (i.e reject invoking a filesystem daemon)
109	.It Fl v	112	.It Fl v
110	Be verbose	113	Be verbose
111	.It Fl D, Ic --daemon Ar daemon	114	.It Fl D, Ic --daemon Ar daemon
Lines 143-150 Link Here
143	Limit size of read requests to	146	Limit size of read requests to
144	.Ar n	147	.Ar n
145	.It Cm private	148	.It Cm private
146	Refuse shared mounting of the daemon. This is the default behaviour,	149	Refuse shared mounting of the daemon.
147	to allow sharing, expicitly use	150	This is the default behaviour, to allow sharing, expicitly use
148	.Fl o Cm noprivate	151	.Fl o Cm noprivate
149	.It Cm neglect_shares	152	.It Cm neglect_shares
150	Do not refuse unmounting if there are secondary mounts	153	Do not refuse unmounting if there are secondary mounts
Lines 154-164 Link Here
154	.El	157	.El
155	.Pp	158	.Pp
156	Besides the above mount options, there is a set of pseudo-mount options which	159	Besides the above mount options, there is a set of pseudo-mount options which
157	are supported by the Fuse library. One can list these by passing	160	are supported by the Fuse library.
		161	One can list these by passing
158	.Fl h	162	.Fl h
159	to a Fuse daemon. Most of these options have effect only on the behaviour of	163	to a Fuse daemon.
160	the daemon (that is, their scope is limited to userspace). However,	164	Most of these options have effect only on the behaviour of the daemon (that is,
161	there are some which do require in-kernel support.	165	their scope is limited to userspace).
		166	However, there are some which do require in-kernel support.
162	Currently the options supported by the kernel are:	167	Currently the options supported by the kernel are:
163	.Bl -tag -width indent	168	.Bl -tag -width indent
164	.It Cm direct_io	169	.It Cm direct_io
Lines 189-195 Link Here
189	real gid) as the user.	194	real gid) as the user.
190	.Pp	195	.Pp
191	This is applied for Fuse mounts by default and only root can mount without	196	This is applied for Fuse mounts by default and only root can mount without
192	the strict access policy (ie. the	197	the strict access policy (i.e the
193	.Cm allow_other	198	.Cm allow_other
194	mount option).	199	mount option).
195	.Pp	200	.Pp
Lines 201-207 Link Here
201	are concerned) by doing their own secondary mount (See	206	are concerned) by doing their own secondary mount (See
202	.Sx SHARED MOUNTS ) .	207	.Sx SHARED MOUNTS ) .
203	.Sh SHARED MOUNTS	208	.Sh SHARED MOUNTS
204	A Fuse daemon can be shared (ie. mounted multiple times).	209	A Fuse daemon can be shared (i.e mounted multiple times).
205	When doing the first (primary) mount, the spawner and the mounter of the daemon	210	When doing the first (primary) mount, the spawner and the mounter of the daemon
206	must have the same uid, or the mounter should be the superuser.	211	must have the same uid, or the mounter should be the superuser.
207	.Pp	212	.Pp
Lines 212-239 Link Here
212	links: they redirect all filesystem operations to the primary mount.	217	links: they redirect all filesystem operations to the primary mount.
213	.Pp	218	.Pp
214	Doing a secondary mount is like signing an agreement: by this action, the mounter	219	Doing a secondary mount is like signing an agreement: by this action, the mounter
215	agrees that the Fuse daemon can trace her I/O activities. From then on	220	agrees that the Fuse daemon can trace her I/O activities.
216	she is not banned from using the filesystem (either via her own mount or	221	From then on she is not banned from using the filesystem
217	via the primary mount), regardless whether	222	(either via her own mount or via the primary mount), regardless whether
218	.Cm allow_other	223	.Cm allow_other
219	is used or not.	224	is used or not.
220	.Pp	225	.Pp
221	The device name of a secondary mount is the device name of the corresponding	226	The device name of a secondary mount is the device name of the corresponding
222	primary mount, followed by a '#' character and the index of the secondary	227	primary mount, followed by a '#' character and the index of the secondary
223	mount; e.g.	228	mount; e.g
224	.Pa /dev/fuse0#3 .	229	.Pa /dev/fuse0#3 .
225	.Sh SECURITY	230	.Sh SECURITY
226	System administrators might want to use a custom mount policy (ie., one going	231	System administrators might want to use a custom mount policy (ie., one going
227	beyond the	232	beyond the
228	.Va vfs.usermount	233	.Va vfs.usermount
229	sysctl). The primary tool for such purposes is	234	sysctl).
		235	The primary tool for such purposes is
230	.Xr sudo 8 .	236	.Xr sudo 8 .
231	However, given that	237	However, given that
232	.Nm	238	.Nm
233	is capable of invoking an arbitrary program, one must be careful when doing this.	239	is capable of invoking an arbitrary program, one must be careful when doing this.
234	.Nm	240	.Nm
235	is designed in a way such that it makes that easy. For this purpose,	241	is designed in a way such that it makes that easy.
236	there are options which disable certain risky features (ie.	242	For this purpose, there are options which disable certain risky features (i.e
237	.Fl S	243	.Fl S
238	and	244	and
239	.Fl A ) ,	245	.Fl A ) ,
Lines 269-276 Link Here
269	.Nm	275	.Nm
270	will ignore uknown mount options.	276	will ignore uknown mount options.
271	.It Ev MOUNT_FUSEFS_CALL_BY_LIB	277	.It Ev MOUNT_FUSEFS_CALL_BY_LIB
272	Adjust behaviour to the needs of the FUSE library. Currently it effects	278	Adjust behaviour to the needs of the FUSE library.
273	help output.	279	Currently it effects help output.
274	.El	280	.El
275	.Pp	281	.Pp
276	Although the following variables do not have any effect on	282	Although the following variables do not have any effect on
Lines 278-288 Link Here
278	itself, they affect the behaviour of fuse daemons:	284	itself, they affect the behaviour of fuse daemons:
279	.Bl -tag -width ".Ev FUSE_DEV_NAME"	285	.Bl -tag -width ".Ev FUSE_DEV_NAME"
280	.It Ev FUSE_DEV_NAME	286	.It Ev FUSE_DEV_NAME
281	Device to attach. If not set, the multiplexer path	287	Device to attach.
		288	If not set, the multiplexer path
282	.Ar /dev/fuse	289	.Ar /dev/fuse
283	is used.	290	is used.
284	.It Ev FUSE_DEV_FD	291	.It Ev FUSE_DEV_FD
285	File desciptor of an opened Fuse device to use. Overrides	292	File desciptor of an opened Fuse device to use.
		293	Overrides
286	.Ev FUSE_DEV_NAME .	294	.Ev FUSE_DEV_NAME .
287	.It Ev FUSE_NO_MOUNT	295	.It Ev FUSE_NO_MOUNT
288	If set, the library will not attempt to mount the filesystem, even	296	If set, the library will not attempt to mount the filesystem, even
Lines 293-299 Link Here
293	.It Pa /dev/fuse	301	.It Pa /dev/fuse
294	Fuse device with which the kernel and Fuse daemons can communicate.	302	Fuse device with which the kernel and Fuse daemons can communicate.
295	.It Pa /dev/fuse	303	.It Pa /dev/fuse
296	The multiplexer path. An	304	The multiplexer path.
		305	An
297	.Xr open 2	306	.Xr open 2
298	performed on it automatically is passed to a free Fuse device by the kernel	307	performed on it automatically is passed to a free Fuse device by the kernel
299	(which might be created just for this puprose).	308	(which might be created just for this puprose).
Lines 330-341 Link Here
330	.Xr umount 8	339	.Xr umount 8
331	.Sh HISTORY	340	.Sh HISTORY
332	.Nm	341	.Nm
333	appears as the part of the FreeBSD implementation of the Fuse userspace filesystem	342	appeared in
334	framework (see http://fuse.sourceforge.net). This user interface is FreeBSD specific.	343	.Fx 10.0
		344	as the part of the
		345	.Fx
		346	implementation of the Fuse userspace filesystem
		347	framework (see http://fuse.sourceforge.net).
335	.Sh CAVEATS	348	.Sh CAVEATS
336	Secondary mounts should be unmounted via their device name. If an attempt is	349	This user interface is
337	made to be unmount them via their filesystem root path, the unmount request	350	.Fx
338	will be forwarded to the primary mount path.	351	specific.
		352	Secondary mounts should be unmounted via their device name.
		353	If an attempt is made to be unmount them via their filesystem root path,
		354	the unmount request will be forwarded to the primary mount path.
339	In general, unmounting by device name is less error-prone than by mount path	355	In general, unmounting by device name is less error-prone than by mount path
340	(although the latter will also work under normal circumstances).	356	(although the latter will also work under normal circumstances).
341	.Pp	357	.Pp