1 files changed, 475 insertions, 0 deletions

diff --git a/fs/cifs/README b/fs/cifs/README
new file mode 100644
index 000000000000..0f20edc935b5
--- /dev/null
+++ b/fs/cifs/README
@@ -0,0 +1,475 @@
+The CIFS VFS support for Linux supports many advanced network filesystem 
+features such as heirarchical dfs like namespace, hardlinks, locking and more.  
+It was designed to comply with the SNIA CIFS Technical Reference (which 
+supersedes the 1992 X/Open SMB Standard) as well as to perform best practice 
+practical interoperability with Windows 2000, Windows XP, Samba and equivalent 
+servers.  
+
+For questions or bug reports please contact:
+    sfrench@samba.org (sfrench@us.ibm.com) 
+
+Build instructions:
+==================
+For Linux 2.4:
+1) Get the kernel source (e.g.from http://www.kernel.org)
+and download the cifs vfs source (see the project page
+at http://us1.samba.org/samba/Linux_CIFS_client.html)
+and change directory into the top of the kernel directory
+then patch the kernel (e.g. "patch -p1 < cifs_24.patch") 
+to add the cifs vfs to your kernel configure options if
+it has not already been added (e.g. current SuSE and UL
+users do not need to apply the cifs_24.patch since the cifs vfs is
+already in the kernel configure menu) and then
+mkdir linux/fs/cifs and then copy the current cifs vfs files from
+the cifs download to your kernel build directory e.g.
+
+        cp <cifs_download_dir>/fs/cifs/* to <kernel_download_dir>/fs/cifs
+        
+2) make menuconfig (or make xconfig)
+3) select cifs from within the network filesystem choices
+4) save and exit
+5) make dep
+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)
+2) make menuconfig (or make xconfig)
+3) select cifs from within the network filesystem choices
+4) save and exit
+5) make
+
+
+Installation instructions:
+=========================
+If you have built the CIFS vfs as module (successfully) simply
+type "make modules_install" (or if you prefer, manually copy the file to
+the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.o).
+
+If you have built the CIFS vfs into the kernel itself, follow the instructions
+for your distribution on how to install a new kernel (usually you
+would simply type "make install").
+
+If you do not have the utility mount.cifs (in the Samba 3.0 source tree and on 
+the CIFS VFS web site) copy it to the same directory in which mount.smbfs and 
+similar files reside (usually /sbin).  Although the helper software is not  
+required, mount.cifs is recommended.  Eventually the Samba 3.0 utility program 
+"net" may also be helpful since it may someday provide easier mount syntax for
+users who are used to Windows e.g.  net use <mount point> <UNC name or cifs URL>
+Note that running the Winbind pam/nss module (logon service) on all of your
+Linux clients is useful in mapping Uids and Gids consistently across the
+domain to the proper network user.  The mount.cifs mount helper can be
+trivially built from Samba 3.0 or later source e.g. by executing:
+
+        gcc samba/source/client/mount.cifs.c -o mount.cifs
+
+If cifs is built as a module, then the size and number of network buffers
+and maximum number of simultaneous requests to one server can be configured.
+Changing these from their defaults is not recommended. By executing modinfo
+        modinfo kernel/fs/cifs/cifs.ko
+on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made
+at module initialization time (by running insmod cifs.ko) can be seen.
+
+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 
+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
+unmount it e.g.
+//server/usersharename  /mnt/username cifs user 0 0
+
+Note that when the mount.cifs utility is run suid (allowing user mounts), 
+in order to reduce risks, the "nosuid" mount flag is passed in on mount to
+disallow execution of an suid program mounted on the remote target.
+When mount is executed as root, nosuid is not passed in by default,
+and execution of suid programs on the remote target would be enabled
+by default. This can be changed, as with nfs and other filesystems, 
+by simply specifying "nosuid" among the mount options. For user mounts 
+though to be able to pass the suid flag to mount requires rebuilding 
+mount.cifs with the following flag: 
+ 
+        gcc samba/source/client/mount.cifs.c -DCIFS_ALLOW_USR_SUID -o mount.cifs
+
+There is a corresponding manual page for cifs mounting in the Samba 3.0 and
+later source tree in docs/manpages/mount.cifs.8 
+
+Samba Considerations 
+==================== 
+To get the maximum benefit from the CIFS VFS, we recommend using a server that 
+supports the SNIA CIFS Unix Extensions standard (e.g.  Samba 2.2.5 or later or 
+Samba 3.0) but the CIFS vfs works fine with a wide variety of CIFS servers.  
+Note that uid, gid and file permissions will display default values if you do 
+not have a server that supports the Unix extensions for CIFS (such as Samba 
+2.2.5 or later).  To enable the Unix CIFS Extensions in the Samba server, add 
+the line: 
+
+        unix extensions = yes
+        
+to your smb.conf file on the server.  Note that the following smb.conf settings 
+are also useful (on the Samba server) when the majority of clients are Unix or 
+Linux: 
+
+        case sensitive = yes
+        delete readonly = yes 
+        ea support = yes
+
+Note that server ea support is required for supporting xattrs from the Linux
+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. 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.  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
+newly created files can end up with an unnecessarily restrictive default mode,
+which may not be what you want, although if the CIFS Unix extensions are
+enabled on the server and client, subsequent setattr calls (e.g. chmod) can
+fix the mode.  Note that creating special devices (mknod) remotely 
+may require specifying a mkdev function to Samba if you are not using 
+Samba 3.0.6 or later.  For more information on these see the manual pages
+("man smb.conf") on the Samba server system.  Note that the cifs vfs,
+unlike the smbfs vfs, does not read the smb.conf on the client system 
+(the few optional settings are passed in on mount via -o parameters instead).  
+Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete
+open files (required for strict POSIX compliance).  Windows Servers already 
+supported this feature. Samba server does not allow symlinks that refer to files
+outside of the share, so in Samba versions prior to 3.0.6, most symlinks to
+files with absolute paths (ie beginning with slash) such as:
+         ln -s /mnt/foo bar
+would be forbidden. Samba 3.0.6 server or later includes the ability to create 
+such symlinks safely by converting unsafe symlinks (ie symlinks to server 
+files that are outside of the share) to a samba specific format on the server
+that is ignored by local server applications and non-cifs clients and that will
+not be traversed by the Samba server).  This is opaque to the Linux client
+application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or
+later, but only for remote clients using the CIFS Unix extensions, and will
+be invisbile to Windows clients and typically will not affect local
+applications running on the same server as Samba.  
+
+Use instructions:
+================
+Once the CIFS VFS support is built into the kernel or installed as a module 
+(cifs.o), you can use mount syntax like the following to access Samba or Windows 
+servers: 
+
+  mount -t cifs //9.53.216.11/e$ /mnt -o user=myname,pass=mypassword
+
+Before -o the option -v may be specified to make the mount.cifs
+mount helper display the mount steps more verbosely.  
+After -o the following commonly used cifs vfs specific options
+are supported:
+
+  user=<username>
+  pass=<password>
+  domain=<domain name>
+  
+Other cifs mount options are described below.  Use of TCP names (in addition to
+ip addresses) is available if the mount helper (mount.cifs) is installed. If
+you do not trust the server to which are mounted, or if you do not have
+cifs signing enabled (and the physical network is insecure), consider use
+of the standard mount options "noexec" and "nosuid" to reduce the risk of 
+running an altered binary on your local system (downloaded from a hostile server
+or altered by a hostile router).
+
+Although mounting using format corresponding to the CIFS URL specification is
+not possible in mount.cifs yet, it is possible to use an alternate format
+for the server and sharename (which is somewhat similar to NFS style mount
+syntax) instead of the more widely used UNC format (i.e. \\server\share):
+  mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd
+
+When using the mount helper mount.cifs, passwords may be specified via alternate
+mechanisms, instead of specifying it after -o using the normal "pass=" syntax
+on the command line:
+1) By including it in a credential file. Specify credentials=filename as one
+of the mount options. Credential files contain two lines
+        username=someuser
+        password=your_password
+2) By specifying the password in the PASSWD environment variable (similarly
+the user name can be taken from the USER environment variable).
+3) By specifying the password in a file by name via PASSWD_FILE
+4) By specifying the password in a file by file descriptor via PASSWD_FD
+
+If no password is provided, mount.cifs will prompt for password entry
+
+Restrictions
+============
+Servers must support the NTLM SMB dialect (which is the most recent, supported 
+by Samba and Windows NT version 4, 2000 and XP and many other SMB/CIFS servers) 
+Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC 
+1001/1002 support for "Netbios-Over-TCP/IP." Neither of these is likely to be a 
+problem as most servers support this.  IPv6 support is planned for the future,
+and is almost complete.
+
+Valid filenames differ between Windows and Linux.  Windows typically restricts
+filenames which contain certain reserved characters (e.g.the character : 
+which is used to delimit the beginning of a stream name by Windows), while
+Linux allows a slightly wider set of valid characters in filenames. Windows
+servers can remap such characters when an explicit mapping is specified in
+the Server's registry.  Samba starting with version 3.10 will allow such 
+filenames (ie those which contain valid Linux characters, which normally
+would be forbidden for Windows/CIFS semantics) as long as the server is
+configured for Unix Extensions (and the client has not disabled
+/proc/fs/cifs/LinuxExtensionsEnabled).
+  
+
+CIFS VFS Mount Options
+======================
+A partial list of the supported mount options follows:
+  user          The user name to use when trying to establish
+                the CIFS session.
+  password      The user password.  If the mount helper is
+                installed, the user will be prompted for password
+                if it is not supplied.
+  ip            The ip address of the target server
+  unc           The target server Universal Network Name (export) to 
+                mount.  
+  domain        Set the SMB/CIFS workgroup name prepended to the
+                username during CIFS session establishment
+  uid           If CIFS Unix extensions are not supported by the server
+                this overrides the default uid for inodes. For mounts to
+                servers which do support the CIFS Unix extensions, such
+                as a properly configured Samba server, the server provides
+                the uid, gid and mode.  For servers which do not support
+                the Unix extensions, the default uid (and gid) returned on
+                lookup of existing files is the uid (gid) of the person
+                who executed the mount (root, except when mount.cifs
+                is configured setuid for user mounts) unless the "uid=" 
+                (gid) mount option is specified.  For the uid (gid) of newly
+                created files and directories, ie files created since 
+                the last mount of the server share, the expected uid 
+                (gid) is cached as as long as the inode remains in 
+                memory on the client.   Also note that permission
+                checks (authorization checks) on accesses to a file occur
+                at the server, but there are cases in which an administrator
+                may want to restrict at the client as well.  For those
+                servers which do not report a uid/gid owner
+                (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
+  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
+                this overrides the default mode for file inodes.
+  dir_mode      If CIFS Unix extensions are not supported by the server 
+                this overrides the default mode for directory inodes.
+  port          attempt to contact the server on this tcp port, before
+                trying the usual ports (port 445, then 139).
+  iocharset     Codepage used to convert local path names to and from
+                Unicode. Unicode is used by default for network path
+                names if the server supports it.  If iocharset is
+                not specified then the nls_default specified
+                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
+  rw            mount the network share read-write (note that the
+                server may still consider the share read-only)
+  ro            mount network share read-only
+  version       used to distinguish different versions of the
+                mount helper utility (not typically needed)
+  sep           if first mount option (after the -o), overrides
+                the comma as the separator between the mount
+                parms. e.g.
+                        -o user=myname,password=mypassword,domain=mydom
+                could be passed instead with period as the separator by
+                        -o sep=.user=myname.password=mypassword.domain=mydom
+                this might be useful when comma is contained within username
+                or password or domain. This option is less important
+                when the cifs mount helper cifs.mount (version 1.1 or later)
+                is used.
+  nosuid        Do not allow remote executables with the suid bit 
+                program to be executed.  This is only meaningful for mounts
+                to servers such as Samba which support the CIFS Unix Extensions.
+                If you do not trust the servers in your network (your mount
+                targets) it is recommended that you specify this option for
+                greater security.
+  exec          Permit execution of binaries on the mount.
+  noexec        Do not permit execution of binaries on the mount.
+  dev           Recognize block devices on the remote mount.
+  nodev         Do not recognize devices on the remote mount.
+  suid          Allow remote files on this mountpoint with suid enabled to 
+                be executed (default for mounts when executed as root,
+                nosuid is default for user mounts).
+  credentials   Although ignored by the cifs kernel component, it is used by 
+                the mount helper, mount.cifs. When mount.cifs is installed it
+                opens and reads the credential file specified in order  
+                to obtain the userid and password arguments which are passed to
+                the cifs vfs.
+  guest         Although ignored by the kernel component, the mount.cifs
+                mount helper will not prompt the user for a password
+                if guest is specified on the mount options.  If no
+                password is specified a null password will be used.
+  perm          Client does permission checks (vfs_permission check of uid
+                and gid of the file against the mode and desired operation),
+                Note that this is in addition to the normal ACL check on the
+                target machine done by the server software. 
+                Client permission checking is enabled by default.
+  noperm        Client does not do permission checks.  This can expose
+                files on this mount to access by other users on the local
+                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.
+                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).
+  serverino     Use servers inode numbers instead of generating automatically
+                incrementing inode numbers on the client.  Although this will
+                make it easier to spot hardlinked files (as they will have
+                the same inode numbers) and inode numbers may be persistent,
+                note that the server does not guarantee that the inode numbers
+                are unique if multiple server side mounts are exported under a
+                single share (since inode numbers on the servers might not
+                be unique if multiple filesystems are mounted under the same
+                shared higher level directory).  Note that this requires that
+                the server support the CIFS Unix Extensions as other servers
+                do not return a unique IndexNumber on SMB FindFirst (most
+                servers return zero as the IndexNumber).  Parameter has no
+                effect to Windows servers and others which do not support the
+                CIFS Unix Extensions.
+  noserverino   Client generates inode numbers (rather than using the actual one
+                from the server) by default.
+  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).
+  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.
+  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.
+  direct        Do not do inode data caching on files opened on this mount.
+                This precludes mmaping files on this mount. In some cases
+                with fast networks and little or no caching benefits on the
+                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 
+                (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
+                to be sent to the server.
+  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 
+                
+The mount.cifs mount helper also accepts a few mount options before -o
+including:
+
+        -S      take password from stdin (equivalent to setting the environment
+                variable "PASSWD_FD=0"
+        -V      print mount.cifs version
+        -?      display simple usage information
+
+With recent 2.6 kernel versions of modutils, the version of the cifs kernel
+module can be displayed via modinfo.
+
+Misc /proc/fs/cifs Flags and Debug Info
+=======================================
+Informational pseudo-files:
+DebugData               Displays information about active CIFS sessions
+                        and shares.
+Stats                   Lists summary resource usage information as well as per
+                        share statistics, if CONFIG_CIFS_STATS in enabled
+                        in the kernel configuration.
+
+Configuration pseudo-files:
+MultiuserMount          If set to one, more than one CIFS session to 
+                        the same server ip address can be established
+                        if more than one uid accesses the same mount
+                        point and if the uids user/password mapping
+                        information is available. (default is 0)
+PacketSigningEnabled    If set to one, cifs packet signing is enabled
+                        and will be used if the server requires 
+                        it.  If set to two, cifs packet signing is
+                        required even if the server considers packet
+                        signing optional. (default 1)
+cifsFYI                 If set to one, additional debug information is
+                        logged to the system error log. (default 0)
+ExtendedSecurity        If set to one, SPNEGO session establishment
+                        is allowed which enables more advanced 
+                        secure CIFS session establishment (default 0)
+NTLMV2Enabled           If set to one, more secure password hashes
+                        are used when the server supports them and
+                        when kerberos is not negotiated (default 0)
+traceSMB                If set to one, debug information is logged to the
+                        system error log with the start of smb requests
+                        and responses (default 0)
+LookupCacheEnable       If set to one, inode information is kept cached
+                        for one second improving performance of lookups
+                        (default 1)
+OplockEnabled           If set to one, safe distributed caching enabled.
+                        (default 1)
+LinuxExtensionsEnabled  If set to one then the client will attempt to
+                        use the CIFS "UNIX" extensions which are optional
+                        protocol enhancements that allow CIFS servers
+                        to return accurate UID/GID information as well
+                        as support symbolic links. If you use servers
+                        such as Samba that support the CIFS Unix
+                        extensions but do not want to use symbolic link
+                        support and want to map the uid and gid fields 
+                        to values supplied at mount (rather than the 
+                        actual values, then set this to zero. (default 1)
+
+These experimental features and tracing can be enabled by changing flags in 
+/proc/fs/cifs (after the cifs module has been installed or built into the 
+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
+        
+and for more extensive tracing including the start of smb requests and responses
+
+        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
+
+        DNOTIFY fcntl: needed for support of directory change 
+                            notification and perhaps later for file leases)
+
+Per share (per client mount) statistics are available in /proc/fs/cifs/Stats
+if the kernel was configured with cifs statistics enabled.  The statistics
+represent the number of successful (ie non-zero return code from the server) 
+SMB responses to some of the more common commands (open, delete, mkdir etc.).
+Also recorded is the total bytes read and bytes written to the server for
+that share.  Note that due to client caching effects this can be less than the
+number of bytes read and written by the application running on the client.
+The statistics for the number of total SMBs and oplock breaks are different in
+that they represent all for that share, not just those for which the server
+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.  
+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 
+complete in the CIFS VFS yet).