susmb - Unprivileged mounting of SMB/CIFS shares via FUSE
=========================================================

Introduction
------------

susmb lets you mount SMB/CIFS shares via FUSE, in the vein of the Map Network
Drive functionality in Windows.

The two existing FUSE filesystems that I know of (SMB for FUSE and fusesmb)
mimic Windows' Network Neighbourhood by letting you browse hosts and shares.
This means that you must run a NetBIOS name server and can't see hosts that
aren't advertised via NetBIOS.

You can build [u]mount.cifs in the Samba distribution and install them
setuid root, but that has its own set of security implications. In any
case there's no need for network filesystem code to be in the kernel:
bugs could lead to remotely exploitable kernel vulnerabilities. Running
the SMB client code in user space as an unprivileged user limits the
potential damage due to bugs.

A user space implementation will be slower than a kernel filesystem since
the data must be copied in and out of the fuse process' context as well as
in/out of the user process' context. Mitigating factors are:

1. Increased security.
2. Containment of bugs.
3. Throughput is more likely to be limited by network bandwidth rather than
   local memory copying.
4. The client filesystem code can be upgraded/fixed without kernel changes.


Dependencies
------------

- FUSE 2.6 or later (and probably version <3).
- libsmbclient 4.20+ (part of Samba) - www.samba.org (samba 3.3+ required).


Installation
------------

make
make install   # Maybe as root, depending on your installation prefix.


Configuration and usage
-----------------------

See the man page.


Acknowledgements
----------------

Geoff Johnstone, the main author of the original usmb program.

Jonathan Schultz (Email <firstname> at imatix.com) provided a patch
to fix the display of file modification times.

Stijn Hoop (Email <firstname> at sandcat.nl) provided a patch to fix
a compilation problem on 64-bit platforms.

Nigel Smith (Email me at <firstname>.<surname>.name) contributed the
port to Samba 3.2.

Michal Suchanek (Email hramrach at centrum dot cz) contributed the
Debian packaging and the initial implementation of ~-expansion.


Changes
-------

This is a fork of usmb 20130204
http://repo.or.cz/w/usmb.git/snapshot/aa94e132c12faf1a00f547ea4a96b5728612dea6.tar.gz
(git commit aa94e132c12faf1a00f547ea4a96b5728612dea6)

It has the patches applied from OpenBSD ports 7.6:
https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/sysutils/usmb/

It is mainly tested on OpenBSD (Linux has a SMB/CIFS driver anyway).

Below is a summary of the most important changes:

Performance:

- Set struct stat st.st_blksiz to a higher number for more efficient buffering
  for programs using the standard FILE* stdio interfaces. Huge improvement for
  reads and writes.
  On OpenBSD the default block size for FUSE is 512 bytes.
  This crippled network performance.
  On OpenBSD there is no FUSE caching layer (at time of writing 2025-09-07), so
  each read call had more overhead.
- Remove the hardcoded FUSE mount option max_read=N.
  This crippled network performance.


Security:

- Many code simplifications and deletions (reducing attack surface and makes it
  easier to review).
- Use unveil(2) syscall to lock down much of the filesystem except the
  mountpoint and required FUSE devices.
- Optional privilege dropping support: on OpenBSD FUSE would need to run as root:
  (sysctl kern.usermount was removed around July 2016, around
  commit 65c8a8a0394483b41de8f02c862e65fb529cf538).
  After mounting the filesystem and acquiring access to the FUSE driver
  privileges are dropped. This is not perfect, but at least now the Samba smbclient
  code runs as a user again.
- Remove support for reading the password from the terminal. This can be
  insecure and caused issues when running as a daemon and the network credentials
  changed.


Cleanups:

- Merge everything into one C file for easier code review.
- Remove Samba < 3.3 compatibility layer and code. This is hard to test
  nowadays anyway.
- Use getopt for option parsing: remove dependencies on glib which was used for
  option parsing only.
  Remove long option support.
- Remove libxml2 dependency and configuration via XML. Configuration is now
  done via a simpler syntax as a URI from the command-line. This was also
  listed in the man page under the BUGS section as a wanted feature.
- Remove autoconf and Debian-specific packaging files. Use a simple Makefile.
- Man page rewritten from roff to mandoc.
