README - susmb - fork from usmb 20130204: mount SMB/CIFS shares via FUSE
(HTM) git clone git://git.codemadness.org/susmb
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) README
(DIR) LICENSE
---
README (4531B)
---
1 susmb - Unprivileged mounting of SMB/CIFS shares via FUSE
2 =========================================================
3
4 Introduction
5 ------------
6
7 susmb lets you mount SMB/CIFS shares via FUSE, in the vein of the Map Network
8 Drive functionality in Windows.
9
10 The two existing FUSE filesystems that I know of (SMB for FUSE and fusesmb)
11 mimic Windows' Network Neighbourhood by letting you browse hosts and shares.
12 This means that you must run a NetBIOS name server and can't see hosts that
13 aren't advertised via NetBIOS.
14
15 You can build [u]mount.cifs in the Samba distribution and install them
16 setuid root, but that has its own set of security implications. In any
17 case there's no need for network filesystem code to be in the kernel:
18 bugs could lead to remotely exploitable kernel vulnerabilities. Running
19 the SMB client code in user space as an unprivileged user limits the
20 potential damage due to bugs.
21
22 A user space implementation will be slower than a kernel filesystem since
23 the data must be copied in and out of the fuse process' context as well as
24 in/out of the user process' context. Mitigating factors are:
25
26 1. Increased security.
27 2. Containment of bugs.
28 3. Throughput is more likely to be limited by network bandwidth rather than
29 local memory copying.
30 4. The client filesystem code can be upgraded/fixed without kernel changes.
31
32
33 Dependencies
34 ------------
35
36 - FUSE 2.6 or later (and probably <3).
37 - libsmbclient 4.20+ (part of Samba) - www.samba.org (samba 3.3+ required).
38
39
40 Installation
41 ------------
42
43 make
44 make install # Maybe as root, depending on your installation prefix.
45
46
47 Configuration and usage
48 -----------------------
49
50 See the man page.
51
52
53 Acknowledgements
54 ----------------
55
56 Geoff Johnstone, the main author of the original usmb program.
57
58 Jonathan Schultz (Email <firstname> at imatix.com) provided a patch
59 to fix the display of file modification times.
60
61 Stijn Hoop (Email <firstname> at sandcat.nl) provided a patch to fix
62 a compilation problem on 64-bit platforms.
63
64 Nigel Smith (Email me at <firstname>.<surname>.name) contributed the
65 port to Samba 3.2.
66
67 Michal Suchanek (Email hramrach at centrum dot cz) contributed the
68 Debian packaging and the initial implementation of ~-expansion.
69
70
71 Changes
72 -------
73
74 This is a fork of usmb 20130204
75 http://repo.or.cz/w/usmb.git/snapshot/aa94e132c12faf1a00f547ea4a96b5728612dea6.tar.gz
76 (git commit aa94e132c12faf1a00f547ea4a96b5728612dea6)
77
78 It has the patches applied from OpenBSD ports 7.6:
79 https://cvsweb.openbsd.org/cgi-bin/cvsweb/ports/sysutils/usmb/
80
81 It is mainly tested on OpenBSD (Linux has a SMB/CIFS driver anyway).
82
83 Below is a summary of the most important changes:
84
85 Performance:
86
87 - Set struct stat st.st_blksiz to a higher number for more efficient buffering
88 for programs using the standard FILE* stdio interfaces. Huge improvement for
89 reads and writes.
90 On OpenBSD the default block size for FUSE is 512 bytes.
91 This crippled network performance.
92 On OpenBSD there is no FUSE caching layer (at time of writing 2025-09-07), so
93 each read call had more overhead.
94 - Remove the hardcoded FUSE mount option max_read=N.
95 This crippled network performance.
96
97
98 Security:
99
100 - Many code simplifications and deletions (reducing attack surface and makes it
101 easier to review).
102 - Use unveil(2) syscall to lock down much of the filesystem except the
103 mountpoint and required FUSE devices.
104 - Optional privilege dropping support: on OpenBSD FUSE would need to run as root:
105 (sysctl kern.usermount was removed around July 2016, around
106 commit 65c8a8a0394483b41de8f02c862e65fb529cf538).
107 After mounting the filesystem and acquiring access to the FUSE driver
108 privileges are dropped. This is not perfect, but at least now the Samba smbclient
109 code runs as a user again.
110 - Remove support for reading the password from the terminal. This can be
111 insecure and caused issues when running as a daemon and the network credentials
112 changed.
113
114
115 Cleanups:
116
117 - Merge everything into one C file for easier code review.
118 - Remove Samba < 3.3 compatibility layer and code. This is hard to test
119 nowadays anyway.
120 - Use getopt for option parsing: remove dependences on glib which was used for
121 option parsing only.
122 Remove long option support.
123 - Remove libxml2 dependency and configuration via XML. Configuration is now
124 done via a simpler syntax as a URI from the command-line. This was also
125 listed in the man page under the BUGS section as a wanted feature.
126 - Remove autoconf and Debian-specific packaging files. Use a simple Makefile.
127 - Man page rewritten from roff to mandoc.