README

   1 usmb - Unprivileged mounting of SMB/CIFS shares via FUSE
   2 ========================================================
   3
   4 Acknowledgements
   5 ----------------
   6
   7 Jonathan Schultz (Email <firstname> at imatix.com) provided a patch
   8 to fix the display of file modification times.
   9
  10 Stijn Hoop (Email <firstname> at sandcat.nl) provided a patch to fix
  11 a compilation problem on 64-bit platforms.
  12
  13 Nigel Smith (Email me at <firstname>.<surname>.name) contributed the
  14 port to Samba 3.2.
  15
  16
  17 Introduction
  18 ------------
  19
  20 usmb lets you mount SMB/CIFS shares via FUSE, in the vein of the Map Network
  21 Drive functionality in Windows.
  22
  23 The two existing FUSE filesystems that I know of (SMB for FUSE and fusesmb)
  24 mimic Windows' Network Neighbourhood by letting you browse hosts and shares.
  25 This means that you must run a NetBIOS name server and can't see hosts that
  26 aren't advertised via NetBIOS.
  27
  28 You can build [u]mount.cifs in the Samba distribution and install them
  29 setuid root, but that has its own set of security implications. In any
  30 case there's no need for network filesystem code to be in the kernel:
  31 bugs could lead to remotely exploitable kernel vulnerabilities. Running
  32 the SMB client code in user space as an unprivileged user limits the
  33 potential damage due to bugs.
  34
  35 A user space implementation will be slower than a kernel filesystem since
  36 the data must be copied in and out of the fuse process' context as well as
  37 in/out of the user process' context. Mitigating factors are:
  38
  39 1. Increased security.
  40 2. Containment of bugs.
  41 3. Throughput is more likely to be limited by network bandwidth rather than
  42    local memory copying.
  43 4. The client filesystem code can be upgraded/fixed without kernel changes.
  44
  45
  46 Pre-Requisites
  47 --------------
  48
  49 glib 2.6 or later - www.gtk.org.
  50 libxml2 - ftp.gnome.org.
  51 FUSE 2.6 or later - fuse.sourgeforge.net.
  52 libsmbclient 3.0 (part of Samba) - www.samba.org.
  53
  54 You need GNU sed to build usmb.
  55
  56
  57 Installation
  58 ------------
  59
  60 ./configure
  61 make
  62 make install   # Maybe as root, depending on your installation prefix.
  63
  64 If you don't have a configure script then first run autoreconf; this requires
  65 a recent (post-2.63) version of GNU autoconf to be installed.
  66
  67 If the configure script "Cannot find libsmbclient" then use --with-samba=xxx
  68 to tell it where Samba is installed.
  69
  70
  71 Configuration
  72 -------------
  73
  74 You need an XML configuration file - ${HOME}/.usmb.conf by default. There's an
  75 example in usmb.conf.
  76
  77 There are two main elements: credentials and mounts.
  78
  79 Credentials:
  80
  81   <credentials id="some_id">
  82     <domain>mydomain</domain>
  83     <username>username</username>
  84     <password>password</password>
  85   </credentials>
  86
  87 Each credentials element gives authentication details. You can have multiple
  88 credentials elements; each must have a distinct id attribute. If you omit
  89 the <password> element then usmb will prompt you for a password.
  90
  91 A mount element describes an SMB share:
  92
  93   <mount id="mount_id" credentials="some_id">
  94     <server>1.2.3.4</server>
  95     <share>sharename</share>
  96     <mountpoint>/tmp/share</mountpoint>
  97   </mount>
  98
  99 The credentials attribute identifies the id of the credentials element that
 100 provides authentication details for the share. The server, share and
 101 mountpoint should be self-explanatory. The id is given on the usmb command
 102 line to identify the SMB share to mount.
 103
 104 You can specify multiple mount elements; each must have a distinct id
 105 (though credentials and mount IDs can be the same).
 106
 107 The whole file is wrapped in a <usmbconfig> element.
 108
 109
 110 Usage
 111 -----
 112
 113 $ usmb [options] mount_ID
 114
 115 Use usmb --help for a list of options.
 116 Mount IDs are defined in the configuration file.
 117