Make the use of fusermount(1) explicit

There are multiple ways to mount FUSE filesystems. Processes with
elevated privileges (CAP_SYS_ADMIN) can use the mount(2) syscall
directly or via a suitable helper. libfuse also installs a helper
program, fusermount(1), which is setuid root, to perform this mounting
operation.

Previously, we would attempt the syscall, and then fallback to trying
fusermount (if we can find it) automatically. This is a little bit too
magical, so it's better to make the option explicit.

Author: colinmarc

examples/hello.rs

@@ -145,5 +145,10 @@ fn main() {
     if matches.get_flag("allow-root") {
         options.push(MountOption::AllowRoot);
     }
-    fuser::mount2(HelloFS, mountpoint, &options).unwrap();
+
+    if options.contains(&MountOption::AutoUnmount) {
+        fuser::fusermount(HelloFS, mountpoint, &options).unwrap();
+    } else {
+        fuser::mount2(HelloFS, mountpoint, &options).unwrap();
+    }
 }

examples/simple.rs

@@ -2039,21 +2039,26 @@ fn main() {
         .unwrap()
         .to_string();
 
-    let result = fuser::mount2(
-        SimpleFS::new(
-            data_dir,
-            matches.get_flag("direct-io"),
-            matches.get_flag("suid"),
-        ),
-        mountpoint,
-        &options,
+    let fs = SimpleFS::new(
+        data_dir,
+        matches.get_flag("direct-io"),
+        matches.get_flag("suid"),
     );
+    let result = if options.contains(&MountOption::AutoUnmount) {
+        fuser::fusermount(fs, mountpoint, &options)
+    } else {
+        fuser::mount2(fs, mountpoint, &options)
+    };
+
     if let Err(e) = result {
+        error!("{}", e.to_string());
+
         // Return a special error code for permission denied, which usually indicates that
         // "user_allow_other" is missing from /etc/fuse.conf
         if e.kind() == ErrorKind::PermissionDenied {
-            error!("{}", e.to_string());
             std::process::exit(2);
+        } else {
+            std::process::exit(1);
         }
     }
 }

mount_tests.sh

@@ -18,8 +18,8 @@ function run_allow_root_test {
   useradd fusertest1
   useradd fusertest2
   DIR=$(su fusertest1 -c "mktemp --directory")
-  cargo build --example hello --features libfuse,abi-7-30 > /dev/null 2>&1
-  su fusertest1 -c "target/debug/examples/hello $DIR --allow-root" &
+  cargo build --example hello --features abi-7-30 > /dev/null 2>&1
+  su fusertest1 -c "target/debug/examples/hello $DIR --allow-root --auto_unmount" &
   FUSE_PID=$!
   sleep 2
 
@@ -62,7 +62,7 @@ function test_no_user_allow_other {
   DIR=$(su fusertestnoallow -c "mktemp --directory")
   DATA_DIR=$(su fusertestnoallow -c "mktemp --directory")
   cargo build --example simple $1 > /dev/null 2>&1
-  su fusertestnoallow -c "target/debug/examples/simple -vvv --data-dir $DATA_DIR --mount-point $DIR"
+  su fusertestnoallow -c "target/debug/examples/simple -vvv --data-dir $DATA_DIR --mount-point $DIR --auto_unmount"
   exitCode=$?
   if [[ $exitCode -eq 2 ]]; then
       echo -e "$GREEN OK Detected lack of user_allow_other: $2 $NC"

src/lib.rs

@@ -1016,15 +1016,28 @@ pub fn mount2<FS: Filesystem, P: AsRef<Path>>(
     mountpoint: P,
     options: &[MountOption],
 ) -> io::Result<()> {
-    check_option_conflicts(options)?;
+    check_option_conflicts(options, false)?;
     Session::new(filesystem, mountpoint.as_ref(), options).and_then(|mut se| se.run())
 }
 
+/// Mount the given filesystem using fusermount(1). The binary must exist on
+/// the system and be setuid root.
+pub fn fusermount(
+    filesystem: impl Filesystem,
+    mountpoint: impl AsRef<Path>,
+    options: &[MountOption],
+) -> io::Result<()> {
+    check_option_conflicts(options, true)?;
+    Session::new_fusermount(filesystem, mountpoint, options).and_then(|mut se| se.run())
+}
+
 /// Mount the given filesystem to the given mountpoint. This function spawns
 /// a background thread to handle filesystem operations while being mounted
 /// and therefore returns immediately. The returned handle should be stored
 /// to reference the mounted filesystem. If it's dropped, the filesystem will
 /// be unmounted.
+///
+/// This function requires CAP_SYS_ADMIN to run.
 #[deprecated(note = "use spawn_mount2() instead")]
 pub fn spawn_mount<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef<Path>>(
     filesystem: FS,
@@ -1036,7 +1049,7 @@ pub fn spawn_mount<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef<Path>>(
         .map(|x| Some(MountOption::from_str(x.to_str()?)))
         .collect();
     let options = options.ok_or(ErrorKind::InvalidData)?;
-    Session::new(filesystem, mountpoint.as_ref(), options.as_ref()).and_then(|se| se.spawn())
+    spawn_mount2(filesystem, mountpoint, &options)
 }
 
 /// Mount the given filesystem to the given mountpoint. This function spawns
@@ -1045,12 +1058,31 @@ pub fn spawn_mount<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef<Path>>(
 /// to reference the mounted filesystem. If it's dropped, the filesystem will
 /// be unmounted.
 ///
-/// NOTE: This is the corresponding function to mount2.
+/// NOTE: This is the corresponding function to [mount2], and likewise requires
+/// CAP_SYS_ADMIN.
 pub fn spawn_mount2<'a, FS: Filesystem + Send + 'static + 'a, P: AsRef<Path>>(
     filesystem: FS,
     mountpoint: P,
     options: &[MountOption],
 ) -> io::Result<BackgroundSession> {
-    check_option_conflicts(options)?;
+    check_option_conflicts(options, false)?;
     Session::new(filesystem, mountpoint.as_ref(), options).and_then(|se| se.spawn())
 }
+
+/// Mount the given filesystem to the given mountpoint. This function spawns
+/// a background thread to handle filesystem operations while being mounted
+/// and therefore returns immediately. The returned handle should be stored
+/// to reference the mounted filesystem. If it's dropped, the filesystem will
+/// be unmounted.
+///
+/// NOTE: This is the corresponding function to [fusermount]. Unlike
+/// [spawn_mount], this uses fusermount(1), which must be present on the
+/// system and setuid root, to circumvent the need for elevated priveleges.
+pub fn spawn_fusermount<'a, FS: Filesystem + Send + 'static + 'a>(
+    filesystem: FS,
+    mountpoint: impl AsRef<Path>,
+    options: &[MountOption],
+) -> io::Result<BackgroundSession> {
+    check_option_conflicts(options, true)?;
+    Session::new_fusermount(filesystem, mountpoint, options).and_then(|se| se.spawn())
+}

src/mount_options.rs

@@ -86,11 +86,23 @@ impl MountOption {
     }
 }
 
-pub(crate) fn check_option_conflicts(options: &[MountOption]) -> Result<(), io::Error> {
+pub(crate) fn check_option_conflicts(
+    options: &[MountOption],
+    allow_auto_unmount: bool,
+) -> Result<(), io::Error> {
     let mut options_set = HashSet::new();
     options_set.extend(options.iter().cloned());
+
+    if !allow_auto_unmount && options_set.contains(&MountOption::AutoUnmount) {
+        return Err(io::Error::new(
+            ErrorKind::InvalidInput,
+            "AutoUnmount requires the use of fusermount",
+        ));
+    }
+
     let conflicting: HashSet<MountOption> = options.iter().flat_map(conflicts_with).collect();
     let intersection: Vec<MountOption> = conflicting.intersection(&options_set).cloned().collect();
+
     if !intersection.is_empty() {
         Err(io::Error::new(
             ErrorKind::InvalidInput,
@@ -188,8 +200,9 @@ mod test {
 
     #[test]
     fn option_checking() {
-        assert!(check_option_conflicts(&[MountOption::Suid, MountOption::NoSuid]).is_err());
-        assert!(check_option_conflicts(&[MountOption::Suid, MountOption::NoExec]).is_ok());
+        assert!(check_option_conflicts(&[MountOption::Suid, MountOption::NoSuid], true).is_err());
+        assert!(check_option_conflicts(&[MountOption::Suid, MountOption::NoExec], false).is_ok());
+        assert!(check_option_conflicts(&[MountOption::AutoUnmount], true).is_ok());
     }
     #[test]
     fn option_round_trip() {

src/session.rs

@@ -9,18 +9,17 @@ use libc::{EAGAIN, EINTR, ENODEV, ENOENT};
 use log::{info, warn};
 use nix::unistd::geteuid;
 use std::fmt;
+use std::os::fd::OwnedFd;
 use std::path::{Path, PathBuf};
 use std::sync::{Arc, Mutex};
 use std::thread::{self, JoinHandle};
 use std::{io, ops::DerefMut};
 
-use crate::channel::Channel;
 use crate::ll::fuse_abi as abi;
 use crate::request::Request;
-use crate::sys;
 use crate::Filesystem;
 use crate::MountOption;
-
+use crate::{channel::Channel, sys::Mount};
 #[cfg(feature = "abi-7-11")]
 use crate::{channel::ChannelSender, notify::Notifier};
 
@@ -48,7 +47,7 @@ pub struct Session<FS: Filesystem> {
     /// Communication channel to the kernel driver
     ch: Channel,
     /// Handle to the mount.  Dropping this unmounts.
-    mount: Arc<Mutex<Option<sys::Mount>>>,
+    mount: Arc<Mutex<Option<Mount>>>,
     /// Mount point
     mountpoint: PathBuf,
     /// Whether to restrict access to owner, root + owner, or unrestricted
@@ -67,15 +66,28 @@ pub struct Session<FS: Filesystem> {
 }
 
 impl<FS: Filesystem> Session<FS> {
-    /// Create a new session by mounting the given filesystem to the given mountpoint
-    pub fn new<P: AsRef<Path>>(
+    /// Create a new session by mounting the given filesystem to the given
+    /// mountpoint. Uses the mount syscall, which requires CAP_SYS_ADMIN.
+    pub fn new(
         filesystem: FS,
-        mountpoint: P,
+        mountpoint: impl AsRef<Path>,
         options: &[MountOption],
-    ) -> io::Result<Session<FS>> {
-        let mountpoint = mountpoint.as_ref();
-        info!("Mounting {}", mountpoint.display());
+    ) -> io::Result<Self> {
+        let (device_fd, mount) = Mount::new_sys(mountpoint.as_ref(), options)?;
+
+        Ok(Self::new_inner(
+            filesystem, mountpoint, device_fd, mount, options,
+        ))
+    }
 
+    /// Create a new session by mounting the given filesystem to the given
+    /// mountpoint. Uses fusermount(1), which must exist on the system and be
+    /// setuid root, to circumvent the elevated privileges required by [Session::new].
+    pub fn new_fusermount(
+        filesystem: FS,
+        mountpoint: impl AsRef<Path>,
+        options: &[MountOption],
+    ) -> io::Result<Session<FS>> {
         // If AutoUnmount is requested, but not AllowRoot or AllowOther we enforce the ACL
         // ourself and implicitly set AllowOther because fusermount needs allow_root or allow_other
         // to handle the auto_unmount option
@@ -86,12 +98,25 @@ impl<FS: Filesystem> Session<FS> {
             warn!("Given auto_unmount without allow_root or allow_other; adding allow_other, with userspace permission handling");
             let mut modified_options = options.to_vec();
             modified_options.push(MountOption::AllowOther);
-            sys::Mount::new(mountpoint, &modified_options)?
+            Mount::new_fusermount(mountpoint.as_ref(), &modified_options)?
         } else {
-            sys::Mount::new(mountpoint, options)?
+            Mount::new_fusermount(mountpoint.as_ref(), options)?
         };
 
+        Ok(Self::new_inner(
+            filesystem, mountpoint, device_fd, mount, options,
+        ))
+    }
+
+    fn new_inner(
+        filesystem: FS,
+        mountpoint: impl AsRef<Path>,
+        device_fd: OwnedFd,
+        mount: Mount,
+        options: &[MountOption],
+    ) -> Self {
         let ch = Channel::new(Arc::new(device_fd));
+
         let allowed = if options.contains(&MountOption::AllowRoot) {
             SessionACL::RootAndOwner
         } else if options.contains(&MountOption::AllowOther) {
@@ -100,18 +125,18 @@ impl<FS: Filesystem> Session<FS> {
             SessionACL::Owner
         };
 
-        Ok(Session {
+        Session {
             filesystem,
             ch,
             mount: Arc::new(Mutex::new(Some(mount))),
-            mountpoint: mountpoint.to_owned(),
+            mountpoint: mountpoint.as_ref().to_owned(),
             allowed,
             session_owner: geteuid().as_raw(),
             proto_major: 0,
             proto_minor: 0,
             initialized: false,
             destroyed: false,
-        })
+        }
     }
 
     /// Return path of the mounted filesystem
@@ -180,7 +205,7 @@ impl<FS: Filesystem> Session<FS> {
 #[derive(Debug)]
 /// A thread-safe object that can be used to unmount a Filesystem
 pub struct SessionUnmounter {
-    mount: Arc<Mutex<Option<sys::Mount>>>,
+    mount: Arc<Mutex<Option<Mount>>>,
 }
 
 impl SessionUnmounter {
@@ -227,7 +252,7 @@ pub struct BackgroundSession {
     #[cfg(feature = "abi-7-11")]
     sender: ChannelSender,
     /// Ensures the filesystem is unmounted when the session ends
-    _mount: sys::Mount,
+    _mount: Mount,
 }
 
 impl BackgroundSession {

src/sys.rs

@@ -61,9 +61,33 @@ pub(crate) struct Mount {
 }
 
 impl Mount {
-    pub fn new(mountpoint: &Path, options: &[MountOption]) -> io::Result<(OwnedFd, Self)> {
-        let mountpoint = mountpoint.canonicalize()?;
-        let (fd, sock) = mount(mountpoint.as_os_str(), options)?;
+    pub fn new_sys(
+        mountpoint: impl AsRef<Path>,
+        options: &[MountOption],
+    ) -> io::Result<(OwnedFd, Self)> {
+        let mountpoint = mountpoint.as_ref().canonicalize()?;
+        let fd = mount_sys(mountpoint.as_os_str(), options)?;
+
+        // Make a dup of the fuse device FD, so we can poll if the filesystem
+        // is still mounted.
+        let fuse_device = fd.as_fd().try_clone_to_owned()?;
+
+        Ok((
+            fd,
+            Self {
+                mountpoint: CString::new(mountpoint.as_os_str().as_bytes())?,
+                fuse_device,
+                auto_unmount_socket: None,
+            },
+        ))
+    }
+
+    pub fn new_fusermount(
+        mountpoint: impl AsRef<Path>,
+        options: &[MountOption],
+    ) -> io::Result<(OwnedFd, Self)> {
+        let mountpoint = mountpoint.as_ref().canonicalize()?;
+        let (fd, sock) = mount_fusermount(mountpoint.as_os_str(), options)?;
 
         // Make a dup of the fuse device FD, so we can poll if the filesystem
         // is still mounted.
@@ -106,22 +130,6 @@ impl Drop for Mount {
     }
 }
 
-fn mount(mountpoint: &OsStr, options: &[MountOption]) -> io::Result<(OwnedFd, Option<UnixStream>)> {
-    if options.contains(&MountOption::AutoUnmount) {
-        // Auto unmount is only supported via fusermount
-        return mount_fusermount(mountpoint, options);
-    }
-
-    match mount_sys(mountpoint, options) {
-        Err(e) if e.kind() == io::ErrorKind::PermissionDenied => {
-            // Retry
-            mount_fusermount(mountpoint, options)
-        }
-        Err(e) => Err(e),
-        Ok(fd) => Ok((fd, None)),
-    }
-}
-
 fn fuse_unmount_pure(mountpoint: &CStr) {
     #[cfg(target_os = "linux")]
     unsafe {
@@ -604,7 +612,7 @@ mod test {
         // deadlock.
         let tmp = ManuallyDrop::new(tempfile::tempdir().unwrap());
         let device_fd = open_device().unwrap();
-        let mount = Mount::new(tmp.path(), &[]).unwrap();
+        let mount = Mount::new_fusermount(tmp.path(), &[]).unwrap();
 
         let mnt = cmd_mount();
         eprintln!("Our mountpoint: {:?}\nfuse mounts:\n{}", tmp.path(), mnt,);

tests/integration_tests.rs

@@ -13,7 +13,7 @@ fn unmount_no_send() {
     impl Filesystem for NoSendFS {}
 
     let tmpdir: TempDir = tempfile::tempdir().unwrap();
-    let mut session = Session::new(NoSendFS(Rc::new(())), tmpdir.path(), &[]).unwrap();
+    let mut session = Session::new_fusermount(NoSendFS(Rc::new(())), tmpdir.path(), &[]).unwrap();
     let mut unmounter = session.unmount_callable();
     thread::spawn(move || {
         thread::sleep(Duration::from_secs(1));