linux 2.6.16.38 w/ vs2.0.3-rc1
[linux-2.6.git] / fs / cifs / README
index 1643ef5..b0070d1 100644 (file)
@@ -32,9 +32,9 @@ the cifs download to your kernel build directory e.g.
 6) make modules (or "make" if CIFS VFS not to be built as a module)
 
 For Linux 2.6:
-1) Download the kernel (e.g. from http://www.kernel.org or from bitkeeper
-at bk://linux.bkbits.net/linux-2.5) and change directory into the top
-of the kernel directory tree (e.g. /usr/src/linux-2.5.73)
+1) Download the kernel (e.g. from http://www.kernel.org)
+and change directory into the top of the kernel directory tree
+(e.g. /usr/src/linux-2.5.73)
 2) make menuconfig (or make xconfig)
 3) select cifs from within the network filesystem choices
 4) save and exit
@@ -75,7 +75,7 @@ Allowing User Mounts
 ====================
 To permit users to mount and unmount over directories they own is possible
 with the cifs vfs.  A way to enable such mounting is to mark the mount.cifs
-utility as suid (e.g. "chmod +s /sbin/mount/cifs). To enable users to 
+utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to 
 umount shares they mount requires
 1) mount.cifs version 1.4 or later
 2) an entry for the share in /etc/fstab indicating that a user may
@@ -97,6 +97,26 @@ mount.cifs with the following flag:
 There is a corresponding manual page for cifs mounting in the Samba 3.0 and
 later source tree in docs/manpages/mount.cifs.8 
 
+Allowing User Unmounts
+======================
+To permit users to ummount directories that they have user mounted (see above),
+the utility umount.cifs may be used.  It may be invoked directly, or if 
+umount.cifs is placed in /sbin, umount can invoke the cifs umount helper
+(at least for most versions of the umount utility) for umount of cifs
+mounts, unless umount is invoked with -i (which will avoid invoking a umount
+helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked
+as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions
+allow adding entries to a file to the /etc/permissions file to achieve the
+equivalent suid effect).  For this utility to succeed the target path
+must be a cifs mount, and the uid of the current user must match the uid
+of the user who mounted the resource.
+
+Also note that the customary way of allowing user mounts and unmounts is 
+(instead of using mount.cifs and unmount.cifs as suid) to add a line
+to the file /etc/fstab for each //server/share you wish to mount, but
+this can become unwieldy when potential mount targets include many
+or  unpredictable UNC names.
+
 Samba Considerations 
 ==================== 
 To get the maximum benefit from the CIFS VFS, we recommend using a server that 
@@ -122,12 +142,14 @@ cifs client, and that EA support is present in later versions of Samba (e.g.
 3.0.6 and later (also EA support works in all versions of Windows, at least to
 shares on NTFS filesystems).  Extended Attribute (xattr) support is an optional
 feature of most Linux filesystems which may require enabling via
-make menuconfig.
+make menuconfig. Client support for extended attributes (user xattr) can be
+disabled on a per-mount basis by specifying "nouser_xattr" on mount.
 
 The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers
 version 3.10 and later.  Setting POSIX ACLs requires enabling both XATTR and 
 then POSIX support in the CIFS configuration options when building the cifs
-module.
+module.  POSIX ACL support can be disabled on a per mount basic by specifying
+"noacl" on mount.
  
 Some administrators may want to change Samba's smb.conf "map archive" and 
 "create mask" parameters from the default.  Unless the create mask is changed
@@ -256,7 +278,9 @@ A partial list of the supported mount options follows:
                (such as Windows), permissions can also be checked at the
                client, and a crude form of client side permission checking 
                can be enabled by specifying file_mode and dir_mode on 
-               the client
+               the client.  Note that the mount.cifs helper must be
+               at version 1.10 or higher to support specifying the uid
+               (or gid) in non-numberic form.
   gid          If CIFS Unix extensions are not supported by the server
                this overrides the default gid for inodes.
   file_mode     If CIFS Unix extensions are not supported by the server
@@ -272,8 +296,10 @@ A partial list of the supported mount options follows:
                during the local client kernel build will be used.
                If server does not support Unicode, this parameter is
                unused.
-  rsize                default read size
-  wsize                default write size
+  rsize                default read size (usually 16K)
+  wsize                default write size (usually 16K, 32K is often better over GigE)
+               maximum wsize currently allowed by CIFS is 57344 (14 4096 byte
+               pages)
   rw           mount the network share read-write (note that the
                server may still consider the share read-only)
   ro           mount network share read-only
@@ -321,7 +347,10 @@ A partial list of the supported mount options follows:
                client system. It is typically only needed when the server
                supports the CIFS Unix Extensions but the UIDs/GIDs on the
                client and server system do not match closely enough to allow
-               access by the user doing the mount.
+               access by the user doing the mount, but it may be useful with
+               non CIFS Unix Extension mounts for cases in which the default
+               mode is specified on the mount but is not to be enforced on the
+               client (e.g. perhaps when MultiUserMount is enabled)
                Note that this does not affect the normal ACL check on the
                target machine done by the server software (of the server
                ACL against the user name provided at mount time).
@@ -344,15 +373,21 @@ A partial list of the supported mount options follows:
   setuids       If the CIFS Unix extensions are negotiated with the server
                the client will attempt to set the effective uid and gid of
                the local process on newly created files, directories, and
-               devices (create, mkdir, mknod).
+               devices (create, mkdir, mknod).  If the CIFS Unix Extensions
+               are not negotiated, for newly created files and directories
+               instead of using the default uid and gid specified on the
+               the mount, cache the new file's uid and gid locally which means
+               that the uid for the file can change when the inode is
+               reloaded (or the user remounts the share).
   nosetuids     The client will not attempt to set the uid and gid on
                on newly created files, directories, and devices (create, 
                mkdir, mknod) which will result in the server setting the
                uid and gid to the default (usually the server uid of the
-               usern who mounted the share).  Letting the server (rather than
-               the client) set the uid and gid is the default. This
-               parameter has no effect if the CIFS Unix Extensions are not
-               negotiated.
+               user who mounted the share).  Letting the server (rather than
+               the client) set the uid and gid is the default. If the CIFS
+               Unix Extensions are not negotiated then the uid and gid for
+               new files will appear to be the uid (gid) of the mounter or the
+               uid (gid) parameter specified on the mount.
   netbiosname   When mounting to servers via port 139, specifies the RFC1001
                source name to use to represent the client netbios machine 
                name when doing the RFC1001 netbios session initialize.
@@ -362,7 +397,7 @@ A partial list of the supported mount options follows:
                client (e.g. when the application is doing large sequential
                reads bigger than page size without rereading the same data) 
                this can provide better performance than the default
-               behavior which caches reads (reaadahead) and writes 
+               behavior which caches reads (readahead) and writes 
                (writebehind) through the local Linux client pagecache 
                if oplock (caching token) is granted and held. Note that
                direct allows write operations larger than page size
@@ -370,7 +405,48 @@ A partial list of the supported mount options follows:
   acl          Allow setfacl and getfacl to manage posix ACLs if server
                supports them.  (default)
   noacl        Do not allow setfacl and getfacl calls on this mount
-               
+  user_xattr    Allow getting and setting user xattrs as OS/2 EAs (extended
+               attributes) to the server (default) e.g. via setfattr 
+               and getfattr utilities. 
+  nouser_xattr  Do not allow getfattr/setfattr to get/set xattrs 
+  mapchars      Translate six of the seven reserved characters (not backslash)
+                       *?<>|:
+               to the remap range (above 0xF000), which also
+               allows the CIFS client to recognize files created with
+               such characters by Windows's POSIX emulation. This can
+               also be useful when mounting to most versions of Samba
+               (which also forbids creating and opening files
+               whose names contain any of these seven characters).
+               This has no effect if the server does not support
+               Unicode on the wire.
+ nomapchars     Do not translate any of these seven characters (default).
+ nocase         Request case insensitive path name matching (case
+               sensitive is the default if the server suports it).
+ nobrl          Do not send byte range lock requests to the server.
+               This is necessary for certain applications that break
+               with cifs style mandatory byte range locks (and most
+               cifs servers do not yet support requesting advisory
+               byte range locks).
+ remount        remount the share (often used to change from ro to rw mounts
+               or vice versa)
+ sfu            When the CIFS Unix Extensions are not negotiated, attempt to
+               create device files and fifos in a format compatible with
+               Services for Unix (SFU).  In addition retrieve bits 10-12
+               of the mode via the SETFILEBITS extended attribute (as
+               SFU does).  In the future the bottom 9 bits of the mode
+               mode also will be emulated using queries of the security
+               descriptor (ACL).
+sec            Security mode.  Allowed values are:
+                       none    attempt to connection as a null user (no name)
+                       krb5    Use Kerberos version 5 authentication
+                       krb5i   Use Kerberos authentication and packet signing
+                       ntlm    Use NTLM password hashing (default)
+                       ntlmi   Use NTLM password hashing with signing (if
+                               /proc/fs/cifs/PacketSigningEnabled on or if
+                               server requires signing also can be the default) 
+                       ntlmv2  Use NTLMv2 password hashing      
+                       ntlmv2i Use NTLMv2 password hashing with packet signing
+
 The mount.cifs mount helper also accepts a few mount options before -o
 including:
 
@@ -386,7 +462,7 @@ Misc /proc/fs/cifs Flags and Debug Info
 =======================================
 Informational pseudo-files:
 DebugData              Displays information about active CIFS sessions
-                       and shares.
+                       and shares, as well as the cifs.ko version.
 Stats                  Lists summary resource usage information as well as per
                        share statistics, if CONFIG_CIFS_STATS in enabled
                        in the kernel configuration.
@@ -434,16 +510,23 @@ These experimental features and tracing can be enabled by changing flags in
 kernel, e.g.  insmod cifs).  To enable a feature set it to 1 e.g.  to enable 
 tracing to the kernel message log type: 
 
-       echo 1 > /proc/fs/cifs/cifsFYI
+       echo 7 > /proc/fs/cifs/cifsFYI
        
-and for more extensive tracing including the start of smb requests and responses
+cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel
+logging of various informational messages.  2 enables logging of non-zero
+SMB return codes while 4 enables logging of requests that take longer
+than one second to complete (except for byte range lock requests). 
+Setting it to 4 requires defining CONFIG_CIFS_STATS2 manually in the
+source code (typically by setting it in the beginning of cifsglob.h),
+and setting it to seven enables all three.  Finally, tracing
+the start of smb requests and responses can be enabled via:
 
        echo 1 > /proc/fs/cifs/traceSMB
 
 Two other experimental features are under development and to test 
 require enabling CONFIG_CIFS_EXPERIMENTAL
 
-       More efficient write operations and SMB buffer handling
+       More efficient write operations
 
        DNOTIFY fcntl: needed for support of directory change 
                            notification and perhaps later for file leases)
@@ -461,8 +544,8 @@ returned success.
        
 Also note that "cat /proc/fs/cifs/DebugData" will display information about 
 the active sessions and the shares that are mounted.  Note: NTLMv2 enablement 
-will not work since they its implementation is not quite complete yet.
-Do not alter these configuration values unless you are doing specific testing.  
+will not work since its implementation is not quite complete yet. Do not alter
+the ExtendedSecurity configuration value unless you are doing specific testing.
 Enabling extended security works to Windows 2000 Workstations and XP but not to 
 Windows 2000 server or Samba since it does not usually send "raw NTLMSSP" 
 (instead it sends NTLMSSP encapsulated in SPNEGO/GSSAPI, which support is not