fs/cifs/README

   1 The CIFS VFS support for Linux supports many advanced network filesystem
   2 features such as heirarchical dfs like namespace, hardlinks, locking and more.
   3 It was designed to comply with the SNIA CIFS Technical Reference (which supersedes
   4 the 1992 X/Open SMB Standard) as well as to perform best practice practical
   5 interoperability with Windows 2000, Windows XP, Samba and equivalent
   6 servers.
   7
   8 For questions or bug reports please contact sfrench@samba.org (sfrench@us.ibm.com)
   9
  10 Build instructions:
  11 ==================
  12 For Linux 2.4:
  13 1a) Get the linux kernel source with cifs vfs already in it
  14 from bitkeeper via bk://cifs.bkbits.net/linux-2.4
  15 or
  16 1b) Get the kernel source (e.g.from http://www.kernel.org)
  17 and download the cifs vfs source (see the project page
  18 at http://us1.samba.org/samba/Linux_CIFS_client.html)
  19 and change directory into the top of the kernel directory
  20 then patch the kernel (e.g. "patch -p1 < cifs_24.patch")
  21 to add the cifs vfs to your kernel configure options if
  22 it has not already been added (e.g. current SuSE and UL
  23 users do not need to do not need that patch since the cifs vfs is
  24 already in the kernel configure menu) and then
  25 mkdir linux/fs/cifs and then copy the current cifs vfs files from
  26 the cifs download to your kernel build directory e.g.
  27         cp <cifs_download_dir>/fs/cifs/* to <kernel_download_dir>/fs/cifs
  28 2) make menuconfig (or make xconfig)
  29 3) select cifs from within the network filesystem choices
  30 4) save and exit
  31 5) make dep
  32 6) make modules (or "make" if CIFS VFS not to be built as a module)
  33
  34 For Linux 2.5:
  35 1) Download the kernel (e.g. from http://www.kernel.org or from bitkeeper
  36 at bk://linux.bkbits.net/linux-2.5) and change directory into the top
  37 of the kernel directory tree (e.g. /usr/src/linux-2.5.73)
  38 2) make menuconfig (or make xconfig)
  39 3) select cifs from within the network filesystem choices
  40 4) save and exit
  41 5) make
  42
  43
  44 Installation instructions:
  45 =========================
  46 If you have built the CIFS vfs as module (successfully) simply
  47 type "make modules_install" (or if you prefer, manually copy the file to
  48 the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.o).
  49
  50 If you have built the CIFS vfs into the kernel itself, follow the instructions
  51 for your distribution on how to install a new kernel (usually you
  52 would simply type "make install").
  53
  54 If you do not have the utility mount.cifs (in the Samba 3.0 source tree and on
  55 the CIFS VFS web site) copy it to the same directory in which mount.smbfs and
  56 similar files reside (usually /sbin).  Although the helper software is required,
  57 mount.cifs is recommended.  Eventually the Samba 3.0 utility program "net"
  58 may also be helpful since it may someday provide easier mount syntax for users used
  59 to Windows e.g.
  60          net use <mount point> <UNC name or cifs URL>
  61 Note that running Winbind on all of your Linux clients is useful in
  62 in mapping Uids and Gids consistently to the proper network user.
  63
  64 Samba Considerations
  65 ====================
  66 To get the maximum benefit from the CIFS VFS, we recommend using a server that
  67 supports the SNIA CIFS Unix Extensions standard (e.g. Samba 2.2.5 or later or
  68 Samba 3.0) but the CIFS vfs works fine with a wide variety of CIFS servers.
  69 Note that uid, gid and file permissions will display default values if you do
  70 not have a server that supports the Unix extensions for CIFS (such as Samba 2.2.3 or
  71 later).   To enable the Unix CIFS Extensions in the Samba server, add the line:
  72         unix extensions = yes
  73 to your smb.conf file on the server.  Note that the following smb.conf settings are
  74 also useful (on the Samba server) when the majority of clients are Unix
  75 or Linux:
  76         case sensitive = yes
  77         delete readonly = yes
  78 Some administrators also change the "map archive" and the "create mask" parameters
  79 from their defaults. For more information on these see the manual pages
  80 ("man smb.conf") on the Samba server system.  Note that the cifs vfs, unlike the
  81 smbfs vfs, does not read the smb.conf on the client system (the few optional settings
  82 are passed in on mount via -o parameters instead).  Note that Samba 2.2.7 or later
  83 includes a fix that allows the CIFS VFS to delete open files (required for strict
  84 POSIX compliance).  Windows Servers already supported this feature.
  85
  86 Use instructions:
  87 ================
  88 Once the CIFS VFS support is built into the kernel or installed as a module (cifs.o),
  89 you can use mount syntax like the following to access Samba or Windows servers:
  90   mount -t cifs //9.53.216.11/e$ /mnt -o user=myname,pass=mypassword
  91 after -o the following cifs vfs specific options are supported:
  92   user=<username>
  93   pass=<password>
  94   domain=<domain name>
  95 TCP names (in addition to ip addresses) will be available when the mount helper
  96 (mount.cifs) is complete
  97
  98 Restrictions
  99 ============
 100 Servers must support the NTLM SMB dialect (which is the most recent, supported by Samba
 101 and Windows NT, 2000 and XP and many other SMB/CIFS servers) and servers must support
 102 either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC 1001/1002 support for
 103 "Netbios-Over-TCP/IP."  Neither of these is likely to be a problem as most servers
 104 support this.  IPv6 support is planned for the future.
 105
 106 CIFS VFS Mount Options
 107 ======================
 108 A partial list of the supported mount options follows:
 109   user          The user name to use when trying to establish
 110                 the CIFS session.
 111   password      The user password.  If the mount helper is
 112                 installed, the user will be prompted for password
 113                 if it is not supplied.
 114   ip            The ip address of the target server
 115   unc           The target server Universal Network Name (export) to
 116                 mount.
 117   domain        Set the SMB/CIFS workgroup name prepended to the
 118                 username during CIFS session establishment
 119   uid           If CIFS Unix extensions are not supported by the server
 120                 this overrides the default uid for inodes.
 121   gid           If CIFS Unix extensions are not supported by the server
 122                 this overrides the default gid for inodes.
 123   file_mode     If CIFS Unix extensions are not supported by the server
 124                 this overrides the default mode for file inodes.
 125   dir_mode      If CIFS Unix extensions are not supported by the server
 126                 this overrides the default mode for directory inodes.
 127   port          attempt to contact the server on this tcp port, before
 128                 trying the usual ports (port 445, then 139).
 129   rsize         default read size
 130   wsize         default write size
 131   rw            mount the network share read-write (note that the
 132                 server may still consider the share read-only)
 133   ro            mount network share read-only
 134   version       used to distinguish different versions of the
 135                 mount helper utility (not typically needed)
 136
 137 Misc /proc/fs/cifs Flags and Debug Info
 138 =======================================
 139 Informational pseudo-files:
 140   DebugData             Displays information about active CIFS sessions
 141   SimultaneousOps       Counter which holds maximum number of
 142                         simultaneous outstanding SMB/CIFS requests.
 143   Stats                 Lists summary resource usage information
 144
 145 Configuration pseudo-files:
 146   MultiuserMount        If set to one, more than one CIFS session to
 147                         the same server ip address can be established
 148                         if more than one uid accesses the same mount
 149                         point and if the uids user/password mapping
 150                         information is available. (default is 0)
 151   PacketSigningEnabled  If set to one, cifs packet signing is enabled
 152                         (default 0)
 153   cifsFYI               If set to one, additional debug information is
 154                         logged to the system error log. (default 0)
 155   ExtendedSecurity      If set to one, SPNEGO session establishment
 156                         is allowed which enables more advanced
 157                         secure CIFS session establishment (default 0)
 158   NTLMV2Enabled         If set to one, more secure password hashes
 159                         are used when the server supports them and
 160                         when kerberos is not negotiated (default 0)
 161   traceSMB              If set to one, debug information is logged to the
 162                         system error log with the start of smb requests
 163                         and responses (default 0)
 164   LookupCacheEnable     If set to one, inode information is kept cached
 165                         for one second improving performance of lookups
 166                         (default 1)
 167   OplockEnabled         If set to one, safe distributed caching enabled.
 168
 169 These experimental features and tracing can be enabled by changing flags in /proc/fs/cifs
 170 (after the cifs module has been installed or built into the kernel, e.g. insmod cifs).
 171 To enable a feature set it to 1 e.g. to enable tracing to the kernel message log
 172 type:
 173         echo 1 > /proc/fs/cifs/cifsFYI
 174 and for more extensive tracing including the start of smb requests and responses
 175         echo 1 > /proc/fs/cifs/traceSMB
 176 Also note that "cat /proc/fs/cifs/DebugData" will display some information about the
 177 active sessions and the shares that are mounted. NTLMv2 enablement and packet
 178 signing will not work since they the implementation is not quite complete. Do not enable
 179 these flags unless you are doing specific testing.  Enabling extended security works to
 180 Windows 2000 Workstations and XP but not to Windows 2000 server or Samba since it does not
 181 usually send "raw NTLMSSP" (instead it sends NTLMSSP encapsulated in SPNEGO/GSSAPI, which
 182 support is not complete in the CIFS VFS yet).