Differential D21110 Diff 60506 sbin/mount_fusefs/mount_fusefs.8

Changeset View

Standalone View

sbin/mount_fusefs/mount_fusefs.8

	.\" Copyright (c) 1980, 1989, 1991, 1993			.\" Copyright (c) 1980, 1989, 1991, 1993
	.\" The Regents of the University of California.			.\" The Regents of the University of California.
	.\" Copyright (c) 2005, 2006 Csaba Henk			.\" Copyright (c) 2005, 2006 Csaba Henk
	.\" All rights reserved.			.\" All rights reserved.
	.\"			.\"
				.\" Copyright (c) 2019 The FreeBSD Foundation
				.\"
				.\" Portions of this documentation were written by BFF Storage Systems under
				.\" sponsorship from the FreeBSD Foundation.
				.\"
	.\" Redistribution and use in source and binary forms, with or without			.\" Redistribution and use in source and binary forms, with or without
	.\" modification, are permitted provided that the following conditions			.\" modification, are permitted provided that the following conditions
	.\" are met:			.\" are met:
	.\" 1. Redistributions of source code must retain the above copyright			.\" 1. Redistributions of source code must retain the above copyright
	.\" notice, this list of conditions and the following disclaimer.			.\" notice, this list of conditions and the following disclaimer.
	.\" 2. Redistributions in binary form must reproduce the above copyright			.\" 2. Redistributions in binary form must reproduce the above copyright
	.\" notice, this list of conditions and the following disclaimer in the			.\" notice, this list of conditions and the following disclaimer in the
	.\" documentation and/or other materials provided with the distribution.			.\" documentation and/or other materials provided with the distribution.
	Show All 10 Lines
	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)			.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT			.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY			.\" 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			.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	.\" SUCH DAMAGE.			.\" SUCH DAMAGE.
	.\"			.\"
	.\" $FreeBSD$			.\" $FreeBSD$
	.\"			.\"
	.Dd November 17, 2018			.Dd July 31, 2019
	.Dt MOUNT_FUSEFS 8			.Dt MOUNT_FUSEFS 8
	.Os			.Os
	.Sh NAME			.Sh NAME
	.Nm mount_fusefs			.Nm mount_fusefs
	.Nd mount a Fuse file system daemon			.Nd mount a Fuse file system daemon
	.Sh SYNOPSIS			.Sh SYNOPSIS
	.Nm			.Nm
	.Op Fl A			.Op Fl A
	▲ Show 20 Lines • Show All 62 Lines • ▼ Show 20 Lines
	.It Fl A , Ic --reject-allow_other			.It Fl A , Ic --reject-allow_other
	Prohibit the			Prohibit the
	.Cm allow_other			.Cm allow_other
	mount flag.			mount flag.
	Intended for use in scripts and the			Intended for use in scripts and the
	.Xr sudoers 5			.Xr sudoers 5
	file.			file.
	.It Fl S , Ic --safe			.It Fl S , Ic --safe
	Run in safe mode (i.e. reject invoking a filesystem daemon)			Run in safe mode (i.e., reject invoking a filesystem daemon).
	.It Fl v			.It Fl v
	Be verbose			Be verbose.
	.It Fl D, Ic --daemon Ar daemon			.It Fl D , Ic --daemon Ar daemon
	Call the specified			Call the specified
	.Ar daemon			.Ar daemon .
	.It Fl O, Ic --daemon_opts Ar opts			.It Fl O , Ic --daemon_opts Ar opts
	Add			Add
	.Ar opts			.Ar opts
	to the daemon's command line			to the daemon's command line.
	.It Fl s, Ic --special Ar special			.It Fl s , Ic --special Ar special
	Use			Use
	.Ar special			.Ar special
	as special			as special.
	.It Fl m, Ic --mountpath Ar node			.It Fl m , Ic --mountpath Ar node
	Mount on			Mount on
	.Ar node			.Ar node .
	.It Fl h, Ic --help			.It Fl h , Ic --help
	Show help			Show help.
	.It Fl V, Ic --version			.It Fl V , Ic --version
	Show version information			Show version information.
	.It Fl o			.It Fl o
	Mount options are specified via			Mount options are specified via
	.Fl o .			.Fl o .
	The following options are available (and also their negated versions,			The following options are available (and also their negated versions,
	by prefixing them with			by prefixing them with
	.Dq no ) :			.Dq no ) :
	.Bl -tag -width indent			.Bl -tag -width indent
	.It Cm default_permissions
	Enable traditional (file mode based) permission checking in kernel
	.It Cm allow_other			.It Cm allow_other
	Do not apply			Do not apply
	.Sx STRICT ACCESS POLICY .			.Sx STRICT ACCESS POLICY .
	Only root can use this option			Only root can use this option.
				.It Cm async
				I/O to the file system may be done asynchronously.
				Writes may be delayed and/or reordered.
				bcrUnsubmitted Not Done Inline Actions s/may/may be/ bcr: s/may/may be/
				.It Cm default_permissions
				Enable traditional (file mode based) permission checking in kernel.
				bcrUnsubmitted Not Done Inline Actions Is this missing a sentence stop? bcr: Is this missing a sentence stop?
				.It Cm intr
				Allow signals to interrupt operations that are blocked waiting for a reply from the server.
				When this option is in use, system calls may fail with
				.Er EINTR
				whenever a signal is received.
	.It Cm max_read Ns = Ns Ar n			.It Cm max_read Ns = Ns Ar n
	Limit size of read requests to			Limit size of read requests to
	.Ar n			.Ar n .
				.It Cm neglect_shares
				Do not refuse unmounting if there are secondary mounts.
				bcrUnsubmitted Not Done Inline Actions Another missing setence stop here? bcr: Another missing setence stop here?
	.It Cm private			.It Cm private
	Refuse shared mounting of the daemon.			Refuse shared mounting of the daemon.
	This is the default behaviour, to allow sharing, expicitly use			This is the default behaviour, to allow sharing, expicitly use
	.Fl o Cm noprivate			.Fl o Cm noprivate .
	.It Cm neglect_shares
	Do not refuse unmounting if there are secondary mounts
	.It Cm push_symlinks_in			.It Cm push_symlinks_in
	Prefix absolute symlinks with the mountpoint			Prefix absolute symlinks with the mountpoint.
				.It Cm subtype Ns = Ns Ar fsname
				Suffix
				.Ar fsname
				to the file system name as reported by
				.Xr statfs 2 .
				This option can be used to identify the file system implemented by
				.Ar fuse_daemon .
	.El			.El
	.El			.El
	.Pp			.Pp
	Besides the above mount options, there is a set of pseudo-mount options which			Besides the above mount options, there is a set of pseudo-mount options which
	are supported by the Fuse library.			are supported by the Fuse library.
	One can list these by passing			One can list these by passing
	.Fl h			.Fl h
	to a Fuse daemon.			to a Fuse daemon.
	Most of these options only have affect on the behavior of the daemon (that is,			Most of these options only have affect on the behavior of the daemon (that is,
	their scope is limited to userspace).			their scope is limited to userspace).
	However, there are some which do require in-kernel support.			However, there are some which do require in-kernel support.
	Currently the options supported by the kernel are:			Currently the options supported by the kernel are:
	.Bl -tag -width indent			.Bl -tag -width indent
	.It Cm direct_io			.It Cm direct_io
	Bypass the buffer cache system			Bypass the buffer cache system.
	.It Cm kernel_cache			.It Cm kernel_cache
	By default cached buffers of a given file are flushed at each			By default cached buffers of a given file are flushed at each
	.Xr open 2 .			.Xr open 2 .
	This option disables this behaviour			This option disables this behaviour.
	.El			.El
	.Sh DAEMON MOUNTS			.Sh DAEMON MOUNTS
	Usually users do not need to use			Usually users do not need to use
	.Nm			.Nm
	directly, as the Fuse library enables Fuse daemons to invoke			directly, as the Fuse library enables Fuse daemons to invoke
	.Nm .			.Nm .
	That is,			That is,
	.Pp			.Pp
	.Dl fuse_daemon device mountpoint			.Dl fuse_daemon device mountpoint
	.Pp			.Pp
	has the same effect as			has the same effect as
	.Pp			.Pp
	.Dl mount_fusefs auto mountpoint fuse_daemon			.Dl mount_fusefs auto mountpoint fuse_daemon
	.Pp			.Pp
	This is the recommended usage when you want basic usage			This is the recommended usage when you want basic usage
	(eg, run the daemon at a low privilege level but mount it as root).			(eg, run the daemon at a low privilege level but mount it as root).
	.Sh STRICT ACCESS POLICY			.Sh STRICT ACCESS POLICY
	The strict access policy for Fuse filesystems lets one to use the filesystem			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,			only if the filesystem daemon has the same credentials (uid, real uid, gid,
	real gid) as the user.			real gid) as the user.
	.Pp			.Pp
	This is applied for Fuse mounts by default and only root can mount without			This is applied for Fuse mounts by default and only root can mount without
	the strict access policy (i.e. the			the strict access policy (i.e., the
	.Cm allow_other			.Cm allow_other
	mount option).			mount option).
	.Pp			.Pp
	This is to shield users from the daemon			This is to shield users from the daemon
	.Dq spying			.Dq spying
	on their I/O activities.			on their I/O activities.
	.Pp			.Pp
	Users might opt to willingly relax strict access policy (as far they			Users might opt to willingly relax strict access policy (as far they
	are concerned) by doing their own secondary mount (See			are concerned) by doing their own secondary mount (See
	.Sx SHARED MOUNTS ) .			.Sx SHARED MOUNTS ) .
	.Sh SHARED MOUNTS			.Sh SHARED MOUNTS
	A Fuse daemon can be shared (i.e. mounted multiple times).			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			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.			must have the same uid, or the mounter should be the superuser.
	.Pp			.Pp
	After the primary mount is in place, secondary mounts can be done by anyone			After the primary mount is in place, secondary mounts can be done by anyone
	unless this feature is disabled by			unless this feature is disabled by
	.Cm private .			.Cm private .
	The behaviour of a secondary mount is analogous to that of symbolic			The behaviour of a secondary mount is analogous to that of symbolic
	links: they redirect all filesystem operations to the primary mount.			links: they redirect all filesystem operations to the primary mount.
	.Pp			.Pp
	Doing a secondary mount is like signing an agreement: by this action, the mounter			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.			agrees that the Fuse daemon can trace her I/O activities.
	From then on she is not banned from using the filesystem			From then on she is not banned from using the filesystem
	(either via her own mount or via the primary mount), regardless whether			(either via her own mount or via the primary mount), regardless whether
	.Cm allow_other			.Cm allow_other
	is used or not.			is used or not.
	.Pp			.Pp
	The device name of a secondary mount is the device name of the corresponding			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			primary mount, followed by a '#' character and the index of the secondary
	mount; e.g.			mount; e.g.,
	.Pa /dev/fuse0#3 .			.Pa /dev/fuse0#3 .
	.Sh SECURITY			.Sh SECURITY
	System administrators might want to use a custom mount policy (ie., one going			System administrators might want to use a custom mount policy (ie., one going
	beyond the			beyond the
	.Va vfs.usermount			.Va vfs.usermount
	sysctl).			sysctl).
	The primary tool for such purposes is			The primary tool for such purposes is
	.Xr sudo 8 .			.Xr sudo 8 .
	However, given that			However, given that
	.Nm			.Nm
	is capable of invoking an arbitrary program, one must be careful when doing this.			is capable of invoking an arbitrary program, one must be careful when doing this.
	.Nm			.Nm
	is designed in a way such that it makes that easy.			is designed in a way such that it makes that easy.
	For this purpose, there are options which disable certain risky features (i.e.			For this purpose, there are options which disable certain risky features (
	.Fl S			.Fl S
	and			and
	.Fl A ) ,			.Fl A ) ,
	and command line parsing is done in a flexible way: mixing options and			and command line parsing is done in a flexible way: mixing options and
	non-options is allowed, but processing them stops at the third non-option			non-options is allowed, but processing them stops at the third non-option
	argument (after the first two has been utilized as device and mountpoint).			argument (after the first two has been utilized as device and mountpoint).
	The rest of the command line specifies the daemon and its arguments.			The rest of the command line specifies the daemon and its arguments.
	(Alternatively, the daemon, the special and the mount path can be			(Alternatively, the daemon, the special and the mount path can be
	▲ Show 20 Lines • Show All 86 Lines • ▼ Show 20 Lines
	.Xr mount 8 ,			.Xr mount 8 ,
	.Xr sudo 8 ,			.Xr sudo 8 ,
	.Xr umount 8			.Xr umount 8
	.Sh HISTORY			.Sh HISTORY
	.Nm			.Nm
	was written as the part of the			was written as the part of the
	.Fx			.Fx
	implementation of the Fuse userspace filesystem framework (see			implementation of the Fuse userspace filesystem framework (see
	.Xr https://github.com/libfuse/libfuse )			.Lk https://github.com/libfuse/libfuse )
	and first appeared in the			and first appeared in the
	.Pa sysutils/fusefs-kmod			.Pa sysutils/fusefs-kmod
	port, supporting			port, supporting
	.Fx 6.0 .			.Fx 6.0 .
	It was added to the base system in			It was added to the base system in
	.Fx 10.0 .			.Fx 10.0 .
	.Sh CAVEATS			.Sh CAVEATS
	This user interface is			This user interface is
	Show All 29 Lines