Commit | Line | Data |
---|---|---|
1da177e4 | 1 | The CIFS VFS support for Linux supports many advanced network filesystem |
1b3c3714 | 2 | features such as hierarchical dfs like namespace, hardlinks, locking and more. |
1da177e4 LT |
3 | It was designed to comply with the SNIA CIFS Technical Reference (which |
4 | supersedes the 1992 X/Open SMB Standard) as well as to perform best practice | |
5 | practical interoperability with Windows 2000, Windows XP, Samba and equivalent | |
675c4679 SF |
6 | servers. This code was developed in participation with the Protocol Freedom |
7 | Information Foundation. | |
8 | ||
9 | Please see | |
10 | http://protocolfreedom.org/ and | |
11 | http://samba.org/samba/PFIF/ | |
12 | for more details. | |
13 | ||
1da177e4 LT |
14 | |
15 | For questions or bug reports please contact: | |
16 | sfrench@samba.org (sfrench@us.ibm.com) | |
17 | ||
18 | Build instructions: | |
19 | ================== | |
20 | For Linux 2.4: | |
21 | 1) Get the kernel source (e.g.from http://www.kernel.org) | |
22 | and download the cifs vfs source (see the project page | |
23 | at http://us1.samba.org/samba/Linux_CIFS_client.html) | |
24 | and change directory into the top of the kernel directory | |
25 | then patch the kernel (e.g. "patch -p1 < cifs_24.patch") | |
26 | to add the cifs vfs to your kernel configure options if | |
27 | it has not already been added (e.g. current SuSE and UL | |
28 | users do not need to apply the cifs_24.patch since the cifs vfs is | |
29 | already in the kernel configure menu) and then | |
30 | mkdir linux/fs/cifs and then copy the current cifs vfs files from | |
31 | the cifs download to your kernel build directory e.g. | |
32 | ||
33 | cp <cifs_download_dir>/fs/cifs/* to <kernel_download_dir>/fs/cifs | |
34 | ||
35 | 2) make menuconfig (or make xconfig) | |
36 | 3) select cifs from within the network filesystem choices | |
37 | 4) save and exit | |
38 | 5) make dep | |
39 | 6) make modules (or "make" if CIFS VFS not to be built as a module) | |
40 | ||
41 | For Linux 2.6: | |
dfc1e148 AB |
42 | 1) Download the kernel (e.g. from http://www.kernel.org) |
43 | and change directory into the top of the kernel directory tree | |
44 | (e.g. /usr/src/linux-2.5.73) | |
1da177e4 LT |
45 | 2) make menuconfig (or make xconfig) |
46 | 3) select cifs from within the network filesystem choices | |
47 | 4) save and exit | |
48 | 5) make | |
49 | ||
50 | ||
51 | Installation instructions: | |
52 | ========================= | |
53 | If you have built the CIFS vfs as module (successfully) simply | |
54 | type "make modules_install" (or if you prefer, manually copy the file to | |
55 | the modules directory e.g. /lib/modules/2.4.10-4GB/kernel/fs/cifs/cifs.o). | |
56 | ||
57 | If you have built the CIFS vfs into the kernel itself, follow the instructions | |
58 | for your distribution on how to install a new kernel (usually you | |
59 | would simply type "make install"). | |
60 | ||
61 | If you do not have the utility mount.cifs (in the Samba 3.0 source tree and on | |
62 | the CIFS VFS web site) copy it to the same directory in which mount.smbfs and | |
63 | similar files reside (usually /sbin). Although the helper software is not | |
64 | required, mount.cifs is recommended. Eventually the Samba 3.0 utility program | |
65 | "net" may also be helpful since it may someday provide easier mount syntax for | |
f6d09982 SF |
66 | users who are used to Windows e.g. |
67 | net use <mount point> <UNC name or cifs URL> | |
1da177e4 LT |
68 | Note that running the Winbind pam/nss module (logon service) on all of your |
69 | Linux clients is useful in mapping Uids and Gids consistently across the | |
70 | domain to the proper network user. The mount.cifs mount helper can be | |
71 | trivially built from Samba 3.0 or later source e.g. by executing: | |
72 | ||
73 | gcc samba/source/client/mount.cifs.c -o mount.cifs | |
74 | ||
75 | If cifs is built as a module, then the size and number of network buffers | |
76 | and maximum number of simultaneous requests to one server can be configured. | |
77 | Changing these from their defaults is not recommended. By executing modinfo | |
78 | modinfo kernel/fs/cifs/cifs.ko | |
79 | on kernel/fs/cifs/cifs.ko the list of configuration changes that can be made | |
80 | at module initialization time (by running insmod cifs.ko) can be seen. | |
81 | ||
82 | Allowing User Mounts | |
83 | ==================== | |
84 | To permit users to mount and unmount over directories they own is possible | |
85 | with the cifs vfs. A way to enable such mounting is to mark the mount.cifs | |
099a58f6 | 86 | utility as suid (e.g. "chmod +s /sbin/mount.cifs). To enable users to |
1da177e4 LT |
87 | umount shares they mount requires |
88 | 1) mount.cifs version 1.4 or later | |
89 | 2) an entry for the share in /etc/fstab indicating that a user may | |
90 | unmount it e.g. | |
91 | //server/usersharename /mnt/username cifs user 0 0 | |
92 | ||
93 | Note that when the mount.cifs utility is run suid (allowing user mounts), | |
94 | in order to reduce risks, the "nosuid" mount flag is passed in on mount to | |
95 | disallow execution of an suid program mounted on the remote target. | |
96 | When mount is executed as root, nosuid is not passed in by default, | |
97 | and execution of suid programs on the remote target would be enabled | |
98 | by default. This can be changed, as with nfs and other filesystems, | |
99 | by simply specifying "nosuid" among the mount options. For user mounts | |
100 | though to be able to pass the suid flag to mount requires rebuilding | |
101 | mount.cifs with the following flag: | |
102 | ||
103 | gcc samba/source/client/mount.cifs.c -DCIFS_ALLOW_USR_SUID -o mount.cifs | |
104 | ||
105 | There is a corresponding manual page for cifs mounting in the Samba 3.0 and | |
106 | later source tree in docs/manpages/mount.cifs.8 | |
107 | ||
099a58f6 SF |
108 | Allowing User Unmounts |
109 | ====================== | |
110 | To permit users to ummount directories that they have user mounted (see above), | |
111 | the utility umount.cifs may be used. It may be invoked directly, or if | |
0cb766ae | 112 | umount.cifs is placed in /sbin, umount can invoke the cifs umount helper |
099a58f6 | 113 | (at least for most versions of the umount utility) for umount of cifs |
0cb766ae SF |
114 | mounts, unless umount is invoked with -i (which will avoid invoking a umount |
115 | helper). As with mount.cifs, to enable user unmounts umount.cifs must be marked | |
116 | as suid (e.g. "chmod +s /sbin/umount.cifs") or equivalent (some distributions | |
117 | allow adding entries to a file to the /etc/permissions file to achieve the | |
118 | equivalent suid effect). For this utility to succeed the target path | |
119 | must be a cifs mount, and the uid of the current user must match the uid | |
120 | of the user who mounted the resource. | |
099a58f6 SF |
121 | |
122 | Also note that the customary way of allowing user mounts and unmounts is | |
123 | (instead of using mount.cifs and unmount.cifs as suid) to add a line | |
124 | to the file /etc/fstab for each //server/share you wish to mount, but | |
125 | this can become unwieldy when potential mount targets include many | |
126 | or unpredictable UNC names. | |
127 | ||
1da177e4 LT |
128 | Samba Considerations |
129 | ==================== | |
130 | To get the maximum benefit from the CIFS VFS, we recommend using a server that | |
131 | supports the SNIA CIFS Unix Extensions standard (e.g. Samba 2.2.5 or later or | |
132 | Samba 3.0) but the CIFS vfs works fine with a wide variety of CIFS servers. | |
133 | Note that uid, gid and file permissions will display default values if you do | |
134 | not have a server that supports the Unix extensions for CIFS (such as Samba | |
135 | 2.2.5 or later). To enable the Unix CIFS Extensions in the Samba server, add | |
136 | the line: | |
137 | ||
138 | unix extensions = yes | |
139 | ||
140 | to your smb.conf file on the server. Note that the following smb.conf settings | |
141 | are also useful (on the Samba server) when the majority of clients are Unix or | |
142 | Linux: | |
143 | ||
144 | case sensitive = yes | |
145 | delete readonly = yes | |
146 | ea support = yes | |
147 | ||
148 | Note that server ea support is required for supporting xattrs from the Linux | |
149 | cifs client, and that EA support is present in later versions of Samba (e.g. | |
150 | 3.0.6 and later (also EA support works in all versions of Windows, at least to | |
151 | shares on NTFS filesystems). Extended Attribute (xattr) support is an optional | |
152 | feature of most Linux filesystems which may require enabling via | |
153 | make menuconfig. Client support for extended attributes (user xattr) can be | |
154 | disabled on a per-mount basis by specifying "nouser_xattr" on mount. | |
155 | ||
156 | The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba servers | |
157 | version 3.10 and later. Setting POSIX ACLs requires enabling both XATTR and | |
158 | then POSIX support in the CIFS configuration options when building the cifs | |
159 | module. POSIX ACL support can be disabled on a per mount basic by specifying | |
160 | "noacl" on mount. | |
161 | ||
162 | Some administrators may want to change Samba's smb.conf "map archive" and | |
163 | "create mask" parameters from the default. Unless the create mask is changed | |
164 | newly created files can end up with an unnecessarily restrictive default mode, | |
165 | which may not be what you want, although if the CIFS Unix extensions are | |
166 | enabled on the server and client, subsequent setattr calls (e.g. chmod) can | |
167 | fix the mode. Note that creating special devices (mknod) remotely | |
168 | may require specifying a mkdev function to Samba if you are not using | |
169 | Samba 3.0.6 or later. For more information on these see the manual pages | |
170 | ("man smb.conf") on the Samba server system. Note that the cifs vfs, | |
171 | unlike the smbfs vfs, does not read the smb.conf on the client system | |
172 | (the few optional settings are passed in on mount via -o parameters instead). | |
173 | Note that Samba 2.2.7 or later includes a fix that allows the CIFS VFS to delete | |
174 | open files (required for strict POSIX compliance). Windows Servers already | |
175 | supported this feature. Samba server does not allow symlinks that refer to files | |
176 | outside of the share, so in Samba versions prior to 3.0.6, most symlinks to | |
177 | files with absolute paths (ie beginning with slash) such as: | |
178 | ln -s /mnt/foo bar | |
179 | would be forbidden. Samba 3.0.6 server or later includes the ability to create | |
180 | such symlinks safely by converting unsafe symlinks (ie symlinks to server | |
181 | files that are outside of the share) to a samba specific format on the server | |
182 | that is ignored by local server applications and non-cifs clients and that will | |
183 | not be traversed by the Samba server). This is opaque to the Linux client | |
184 | application using the cifs vfs. Absolute symlinks will work to Samba 3.0.5 or | |
185 | later, but only for remote clients using the CIFS Unix extensions, and will | |
186 | be invisbile to Windows clients and typically will not affect local | |
187 | applications running on the same server as Samba. | |
188 | ||
189 | Use instructions: | |
190 | ================ | |
191 | Once the CIFS VFS support is built into the kernel or installed as a module | |
192 | (cifs.o), you can use mount syntax like the following to access Samba or Windows | |
193 | servers: | |
194 | ||
195 | mount -t cifs //9.53.216.11/e$ /mnt -o user=myname,pass=mypassword | |
196 | ||
197 | Before -o the option -v may be specified to make the mount.cifs | |
198 | mount helper display the mount steps more verbosely. | |
199 | After -o the following commonly used cifs vfs specific options | |
200 | are supported: | |
201 | ||
202 | user=<username> | |
203 | pass=<password> | |
204 | domain=<domain name> | |
205 | ||
206 | Other cifs mount options are described below. Use of TCP names (in addition to | |
207 | ip addresses) is available if the mount helper (mount.cifs) is installed. If | |
208 | you do not trust the server to which are mounted, or if you do not have | |
209 | cifs signing enabled (and the physical network is insecure), consider use | |
210 | of the standard mount options "noexec" and "nosuid" to reduce the risk of | |
211 | running an altered binary on your local system (downloaded from a hostile server | |
212 | or altered by a hostile router). | |
213 | ||
214 | Although mounting using format corresponding to the CIFS URL specification is | |
215 | not possible in mount.cifs yet, it is possible to use an alternate format | |
216 | for the server and sharename (which is somewhat similar to NFS style mount | |
217 | syntax) instead of the more widely used UNC format (i.e. \\server\share): | |
218 | mount -t cifs tcp_name_of_server:share_name /mnt -o user=myname,pass=mypasswd | |
219 | ||
220 | When using the mount helper mount.cifs, passwords may be specified via alternate | |
221 | mechanisms, instead of specifying it after -o using the normal "pass=" syntax | |
222 | on the command line: | |
223 | 1) By including it in a credential file. Specify credentials=filename as one | |
224 | of the mount options. Credential files contain two lines | |
225 | username=someuser | |
226 | password=your_password | |
227 | 2) By specifying the password in the PASSWD environment variable (similarly | |
228 | the user name can be taken from the USER environment variable). | |
229 | 3) By specifying the password in a file by name via PASSWD_FILE | |
230 | 4) By specifying the password in a file by file descriptor via PASSWD_FD | |
231 | ||
232 | If no password is provided, mount.cifs will prompt for password entry | |
233 | ||
234 | Restrictions | |
235 | ============ | |
1da177e4 | 236 | Servers must support either "pure-TCP" (port 445 TCP/IP CIFS connections) or RFC |
cea21805 JL |
237 | 1001/1002 support for "Netbios-Over-TCP/IP." This is not likely to be a |
238 | problem as most servers support this. | |
1da177e4 LT |
239 | |
240 | Valid filenames differ between Windows and Linux. Windows typically restricts | |
241 | filenames which contain certain reserved characters (e.g.the character : | |
242 | which is used to delimit the beginning of a stream name by Windows), while | |
243 | Linux allows a slightly wider set of valid characters in filenames. Windows | |
244 | servers can remap such characters when an explicit mapping is specified in | |
245 | the Server's registry. Samba starting with version 3.10 will allow such | |
246 | filenames (ie those which contain valid Linux characters, which normally | |
247 | would be forbidden for Windows/CIFS semantics) as long as the server is | |
248 | configured for Unix Extensions (and the client has not disabled | |
249 | /proc/fs/cifs/LinuxExtensionsEnabled). | |
250 | ||
251 | ||
252 | CIFS VFS Mount Options | |
253 | ====================== | |
254 | A partial list of the supported mount options follows: | |
255 | user The user name to use when trying to establish | |
256 | the CIFS session. | |
257 | password The user password. If the mount helper is | |
258 | installed, the user will be prompted for password | |
f6d09982 | 259 | if not supplied. |
1da177e4 LT |
260 | ip The ip address of the target server |
261 | unc The target server Universal Network Name (export) to | |
262 | mount. | |
263 | domain Set the SMB/CIFS workgroup name prepended to the | |
264 | username during CIFS session establishment | |
f0472d0e SF |
265 | forceuid Set the default uid for inodes based on the uid |
266 | passed in. For mounts to servers | |
4523cc30 SF |
267 | which do support the CIFS Unix extensions, such as a |
268 | properly configured Samba server, the server provides | |
269 | the uid, gid and mode so this parameter should not be | |
270 | specified unless the server and clients uid and gid | |
271 | numbering differ. If the server and client are in the | |
272 | same domain (e.g. running winbind or nss_ldap) and | |
273 | the server supports the Unix Extensions then the uid | |
274 | and gid can be retrieved from the server (and uid | |
275 | and gid would not have to be specifed on the mount. | |
276 | For servers which do not support the CIFS Unix | |
277 | extensions, the default uid (and gid) returned on lookup | |
278 | of existing files will be the uid (gid) of the person | |
1da177e4 LT |
279 | who executed the mount (root, except when mount.cifs |
280 | is configured setuid for user mounts) unless the "uid=" | |
281 | (gid) mount option is specified. For the uid (gid) of newly | |
282 | created files and directories, ie files created since | |
283 | the last mount of the server share, the expected uid | |
cab00891 | 284 | (gid) is cached as long as the inode remains in |
1da177e4 LT |
285 | memory on the client. Also note that permission |
286 | checks (authorization checks) on accesses to a file occur | |
287 | at the server, but there are cases in which an administrator | |
288 | may want to restrict at the client as well. For those | |
289 | servers which do not report a uid/gid owner | |
290 | (such as Windows), permissions can also be checked at the | |
291 | client, and a crude form of client side permission checking | |
292 | can be enabled by specifying file_mode and dir_mode on | |
6473a559 SF |
293 | the client. Note that the mount.cifs helper must be |
294 | at version 1.10 or higher to support specifying the uid | |
f6d09982 | 295 | (or gid) in non-numeric form. |
f0472d0e SF |
296 | forcegid (similar to above but for the groupid instead of uid) |
297 | uid Set the default uid for inodes, and indicate to the | |
298 | cifs kernel driver which local user mounted . If the server | |
299 | supports the unix extensions the default uid is | |
300 | not used to fill in the owner fields of inodes (files) | |
301 | unless the "forceuid" parameter is specified. | |
4523cc30 | 302 | gid Set the default gid for inodes (similar to above). |
1da177e4 LT |
303 | file_mode If CIFS Unix extensions are not supported by the server |
304 | this overrides the default mode for file inodes. | |
305 | dir_mode If CIFS Unix extensions are not supported by the server | |
306 | this overrides the default mode for directory inodes. | |
307 | port attempt to contact the server on this tcp port, before | |
308 | trying the usual ports (port 445, then 139). | |
309 | iocharset Codepage used to convert local path names to and from | |
310 | Unicode. Unicode is used by default for network path | |
311 | names if the server supports it. If iocharset is | |
312 | not specified then the nls_default specified | |
313 | during the local client kernel build will be used. | |
314 | If server does not support Unicode, this parameter is | |
315 | unused. | |
75865f8c SF |
316 | rsize default read size (usually 16K). The client currently |
317 | can not use rsize larger than CIFSMaxBufSize. CIFSMaxBufSize | |
318 | defaults to 16K and may be changed (from 8K to the maximum | |
319 | kmalloc size allowed by your kernel) at module install time | |
320 | for cifs.ko. Setting CIFSMaxBufSize to a very large value | |
321 | will cause cifs to use more memory and may reduce performance | |
322 | in some cases. To use rsize greater than 127K (the original | |
323 | cifs protocol maximum) also requires that the server support | |
324 | a new Unix Capability flag (for very large read) which some | |
325 | newer servers (e.g. Samba 3.0.26 or later) do. rsize can be | |
326 | set from a minimum of 2048 to a maximum of 130048 (127K or | |
327 | CIFSMaxBufSize, whichever is smaller) | |
328 | wsize default write size (default 57344) | |
329 | maximum wsize currently allowed by CIFS is 57344 (fourteen | |
330 | 4096 byte pages) | |
1da177e4 LT |
331 | rw mount the network share read-write (note that the |
332 | server may still consider the share read-only) | |
333 | ro mount network share read-only | |
334 | version used to distinguish different versions of the | |
335 | mount helper utility (not typically needed) | |
336 | sep if first mount option (after the -o), overrides | |
337 | the comma as the separator between the mount | |
338 | parms. e.g. | |
339 | -o user=myname,password=mypassword,domain=mydom | |
340 | could be passed instead with period as the separator by | |
341 | -o sep=.user=myname.password=mypassword.domain=mydom | |
342 | this might be useful when comma is contained within username | |
343 | or password or domain. This option is less important | |
344 | when the cifs mount helper cifs.mount (version 1.1 or later) | |
345 | is used. | |
346 | nosuid Do not allow remote executables with the suid bit | |
347 | program to be executed. This is only meaningful for mounts | |
348 | to servers such as Samba which support the CIFS Unix Extensions. | |
349 | If you do not trust the servers in your network (your mount | |
350 | targets) it is recommended that you specify this option for | |
351 | greater security. | |
352 | exec Permit execution of binaries on the mount. | |
353 | noexec Do not permit execution of binaries on the mount. | |
354 | dev Recognize block devices on the remote mount. | |
355 | nodev Do not recognize devices on the remote mount. | |
356 | suid Allow remote files on this mountpoint with suid enabled to | |
357 | be executed (default for mounts when executed as root, | |
358 | nosuid is default for user mounts). | |
359 | credentials Although ignored by the cifs kernel component, it is used by | |
360 | the mount helper, mount.cifs. When mount.cifs is installed it | |
361 | opens and reads the credential file specified in order | |
362 | to obtain the userid and password arguments which are passed to | |
363 | the cifs vfs. | |
364 | guest Although ignored by the kernel component, the mount.cifs | |
365 | mount helper will not prompt the user for a password | |
366 | if guest is specified on the mount options. If no | |
367 | password is specified a null password will be used. | |
368 | perm Client does permission checks (vfs_permission check of uid | |
369 | and gid of the file against the mode and desired operation), | |
370 | Note that this is in addition to the normal ACL check on the | |
371 | target machine done by the server software. | |
372 | Client permission checking is enabled by default. | |
373 | noperm Client does not do permission checks. This can expose | |
374 | files on this mount to access by other users on the local | |
375 | client system. It is typically only needed when the server | |
376 | supports the CIFS Unix Extensions but the UIDs/GIDs on the | |
377 | client and server system do not match closely enough to allow | |
6473a559 SF |
378 | access by the user doing the mount, but it may be useful with |
379 | non CIFS Unix Extension mounts for cases in which the default | |
380 | mode is specified on the mount but is not to be enforced on the | |
381 | client (e.g. perhaps when MultiUserMount is enabled) | |
1da177e4 LT |
382 | Note that this does not affect the normal ACL check on the |
383 | target machine done by the server software (of the server | |
384 | ACL against the user name provided at mount time). | |
7521a3c5 | 385 | serverino Use server's inode numbers instead of generating automatically |
1da177e4 LT |
386 | incrementing inode numbers on the client. Although this will |
387 | make it easier to spot hardlinked files (as they will have | |
388 | the same inode numbers) and inode numbers may be persistent, | |
389 | note that the server does not guarantee that the inode numbers | |
390 | are unique if multiple server side mounts are exported under a | |
391 | single share (since inode numbers on the servers might not | |
392 | be unique if multiple filesystems are mounted under the same | |
7521a3c5 SF |
393 | shared higher level directory). Note that some older |
394 | (e.g. pre-Windows 2000) do not support returning UniqueIDs | |
395 | or the CIFS Unix Extensions equivalent and for those | |
396 | this mount option will have no effect. Exporting cifs mounts | |
397 | under nfsd requires this mount option on the cifs mount. | |
c5077ec4 SF |
398 | This is now the default if server supports the |
399 | required network operation. | |
1da177e4 | 400 | noserverino Client generates inode numbers (rather than using the actual one |
c5077ec4 SF |
401 | from the server). These inode numbers will vary after |
402 | unmount or reboot which can confuse some applications, | |
403 | but not all server filesystems support unique inode | |
404 | numbers. | |
1da177e4 LT |
405 | setuids If the CIFS Unix extensions are negotiated with the server |
406 | the client will attempt to set the effective uid and gid of | |
407 | the local process on newly created files, directories, and | |
6473a559 SF |
408 | devices (create, mkdir, mknod). If the CIFS Unix Extensions |
409 | are not negotiated, for newly created files and directories | |
cab00891 | 410 | instead of using the default uid and gid specified on |
6473a559 SF |
411 | the mount, cache the new file's uid and gid locally which means |
412 | that the uid for the file can change when the inode is | |
413 | reloaded (or the user remounts the share). | |
1da177e4 LT |
414 | nosetuids The client will not attempt to set the uid and gid on |
415 | on newly created files, directories, and devices (create, | |
416 | mkdir, mknod) which will result in the server setting the | |
417 | uid and gid to the default (usually the server uid of the | |
67594feb | 418 | user who mounted the share). Letting the server (rather than |
6473a559 SF |
419 | the client) set the uid and gid is the default. If the CIFS |
420 | Unix Extensions are not negotiated then the uid and gid for | |
421 | new files will appear to be the uid (gid) of the mounter or the | |
422 | uid (gid) parameter specified on the mount. | |
1da177e4 LT |
423 | netbiosname When mounting to servers via port 139, specifies the RFC1001 |
424 | source name to use to represent the client netbios machine | |
425 | name when doing the RFC1001 netbios session initialize. | |
426 | direct Do not do inode data caching on files opened on this mount. | |
427 | This precludes mmaping files on this mount. In some cases | |
428 | with fast networks and little or no caching benefits on the | |
429 | client (e.g. when the application is doing large sequential | |
430 | reads bigger than page size without rereading the same data) | |
431 | this can provide better performance than the default | |
67594feb | 432 | behavior which caches reads (readahead) and writes |
1da177e4 LT |
433 | (writebehind) through the local Linux client pagecache |
434 | if oplock (caching token) is granted and held. Note that | |
435 | direct allows write operations larger than page size | |
436 | to be sent to the server. | |
437 | acl Allow setfacl and getfacl to manage posix ACLs if server | |
438 | supports them. (default) | |
439 | noacl Do not allow setfacl and getfacl calls on this mount | |
f6d09982 SF |
440 | user_xattr Allow getting and setting user xattrs (those attributes whose |
441 | name begins with "user." or "os2.") as OS/2 EAs (extended | |
442 | attributes) to the server. This allows support of the | |
443 | setfattr and getfattr utilities. (default) | |
ea4c07d7 | 444 | nouser_xattr Do not allow getfattr/setfattr to get/set/list xattrs |
737b758c SF |
445 | mapchars Translate six of the seven reserved characters (not backslash) |
446 | *?<>|: | |
6a0b4824 SF |
447 | to the remap range (above 0xF000), which also |
448 | allows the CIFS client to recognize files created with | |
449 | such characters by Windows's POSIX emulation. This can | |
450 | also be useful when mounting to most versions of Samba | |
451 | (which also forbids creating and opening files | |
452 | whose names contain any of these seven characters). | |
453 | This has no effect if the server does not support | |
454 | Unicode on the wire. | |
455 | nomapchars Do not translate any of these seven characters (default). | |
c46fa8ac SF |
456 | nocase Request case insensitive path name matching (case |
457 | sensitive is the default if the server suports it). | |
f6d09982 | 458 | (mount option "ignorecase" is identical to "nocase") |
82940a46 SF |
459 | posixpaths If CIFS Unix extensions are supported, attempt to |
460 | negotiate posix path name support which allows certain | |
461 | characters forbidden in typical CIFS filenames, without | |
462 | requiring remapping. (default) | |
463 | noposixpaths If CIFS Unix extensions are supported, do not request | |
464 | posix path name support (this may cause servers to | |
465 | reject creatingfile with certain reserved characters). | |
a403a0a3 SF |
466 | nounix Disable the CIFS Unix Extensions for this mount (tree |
467 | connection). This is rarely needed, but it may be useful | |
468 | in order to turn off multiple settings all at once (ie | |
469 | posix acls, posix locks, posix paths, symlink support | |
470 | and retrieving uids/gids/mode from the server) or to | |
471 | work around a bug in server which implement the Unix | |
472 | Extensions. | |
c46fa8ac SF |
473 | nobrl Do not send byte range lock requests to the server. |
474 | This is necessary for certain applications that break | |
475 | with cifs style mandatory byte range locks (and most | |
476 | cifs servers do not yet support requesting advisory | |
477 | byte range locks). | |
13a6e42a SF |
478 | forcemandatorylock Even if the server supports posix (advisory) byte range |
479 | locking, send only mandatory lock requests. For some | |
480 | (presumably rare) applications, originally coded for | |
481 | DOS/Windows, which require Windows style mandatory byte range | |
482 | locking, they may be able to take advantage of this option, | |
483 | forcing the cifs client to only send mandatory locks | |
484 | even if the cifs server would support posix advisory locks. | |
485 | "forcemand" is accepted as a shorter form of this mount | |
486 | option. | |
be652445 SF |
487 | nostrictsync If this mount option is set, when an application does an |
488 | fsync call then the cifs client does not send an SMB Flush | |
489 | to the server (to force the server to write all dirty data | |
490 | for this file immediately to disk), although cifs still sends | |
491 | all dirty (cached) file data to the server and waits for the | |
492 | server to respond to the write. Since SMB Flush can be | |
493 | very slow, and some servers may be reliable enough (to risk | |
494 | delaying slightly flushing the data to disk on the server), | |
495 | turning on this option may be useful to improve performance for | |
496 | applications that fsync too much, at a small risk of server | |
497 | crash. If this mount option is not set, by default cifs will | |
498 | send an SMB flush request (and wait for a response) on every | |
499 | fsync call. | |
2c1b8615 SF |
500 | nodfs Disable DFS (global name space support) even if the |
501 | server claims to support it. This can help work around | |
13a6e42a SF |
502 | a problem with parsing of DFS paths with Samba server |
503 | versions 3.0.24 and 3.0.25. | |
0cb766ae SF |
504 | remount remount the share (often used to change from ro to rw mounts |
505 | or vice versa) | |
cea21805 JL |
506 | cifsacl Report mode bits (e.g. on stat) based on the Windows ACL for |
507 | the file. (EXPERIMENTAL) | |
5e6e6232 | 508 | servern Specify the server 's netbios name (RFC1001 name) to use |
ad7a2926 | 509 | when attempting to setup a session to the server. |
5e6e6232 CG |
510 | This is needed for mounting to some older servers (such |
511 | as OS/2 or Windows 98 and Windows ME) since they do not | |
512 | support a default server name. A server name can be up | |
513 | to 15 characters long and is usually uppercased. | |
6473a559 SF |
514 | sfu When the CIFS Unix Extensions are not negotiated, attempt to |
515 | create device files and fifos in a format compatible with | |
516 | Services for Unix (SFU). In addition retrieve bits 10-12 | |
517 | of the mode via the SETFILEBITS extended attribute (as | |
cab00891 | 518 | SFU does). In the future the bottom 9 bits of the |
6473a559 SF |
519 | mode also will be emulated using queries of the security |
520 | descriptor (ACL). | |
750d1151 SF |
521 | sign Must use packet signing (helps avoid unwanted data modification |
522 | by intermediate systems in the route). Note that signing | |
523 | does not work with lanman or plaintext authentication. | |
95b1cb90 SF |
524 | seal Must seal (encrypt) all data on this mounted share before |
525 | sending on the network. Requires support for Unix Extensions. | |
526 | Note that this differs from the sign mount option in that it | |
527 | causes encryption of data sent over this mounted share but other | |
528 | shares mounted to the same server are unaffected. | |
84210e91 SF |
529 | locallease This option is rarely needed. Fcntl F_SETLEASE is |
530 | used by some applications such as Samba and NFSv4 server to | |
531 | check to see whether a file is cacheable. CIFS has no way | |
532 | to explicitly request a lease, but can check whether a file | |
533 | is cacheable (oplocked). Unfortunately, even if a file | |
534 | is not oplocked, it could still be cacheable (ie cifs client | |
535 | could grant fcntl leases if no other local processes are using | |
536 | the file) for cases for example such as when the server does not | |
537 | support oplocks and the user is sure that the only updates to | |
538 | the file will be from this client. Specifying this mount option | |
539 | will allow the cifs client to check for leases (only) locally | |
540 | for files which are not oplocked instead of denying leases | |
541 | in that case. (EXPERIMENTAL) | |
750d1151 | 542 | sec Security mode. Allowed values are: |
bf820679 SF |
543 | none attempt to connection as a null user (no name) |
544 | krb5 Use Kerberos version 5 authentication | |
545 | krb5i Use Kerberos authentication and packet signing | |
546 | ntlm Use NTLM password hashing (default) | |
547 | ntlmi Use NTLM password hashing with signing (if | |
548 | /proc/fs/cifs/PacketSigningEnabled on or if | |
549 | server requires signing also can be the default) | |
550 | ntlmv2 Use NTLMv2 password hashing | |
551 | ntlmv2i Use NTLMv2 password hashing with packet signing | |
189acaae SF |
552 | lanman (if configured in kernel config) use older |
553 | lanman hash | |
f6d09982 SF |
554 | hard Retry file operations if server is not responding |
555 | soft Limit retries to unresponsive servers (usually only | |
556 | one retry) before returning an error. (default) | |
bf820679 | 557 | |
1da177e4 LT |
558 | The mount.cifs mount helper also accepts a few mount options before -o |
559 | including: | |
560 | ||
561 | -S take password from stdin (equivalent to setting the environment | |
562 | variable "PASSWD_FD=0" | |
563 | -V print mount.cifs version | |
564 | -? display simple usage information | |
565 | ||
8426c39c | 566 | With most 2.6 kernel versions of modutils, the version of the cifs kernel |
1da177e4 LT |
567 | module can be displayed via modinfo. |
568 | ||
569 | Misc /proc/fs/cifs Flags and Debug Info | |
570 | ======================================= | |
571 | Informational pseudo-files: | |
572 | DebugData Displays information about active CIFS sessions | |
09d1db5c | 573 | and shares, as well as the cifs.ko version. |
1da177e4 LT |
574 | Stats Lists summary resource usage information as well as per |
575 | share statistics, if CONFIG_CIFS_STATS in enabled | |
576 | in the kernel configuration. | |
577 | ||
578 | Configuration pseudo-files: | |
579 | MultiuserMount If set to one, more than one CIFS session to | |
580 | the same server ip address can be established | |
581 | if more than one uid accesses the same mount | |
582 | point and if the uids user/password mapping | |
583 | information is available. (default is 0) | |
584 | PacketSigningEnabled If set to one, cifs packet signing is enabled | |
585 | and will be used if the server requires | |
586 | it. If set to two, cifs packet signing is | |
587 | required even if the server considers packet | |
588 | signing optional. (default 1) | |
254e55ed SF |
589 | SecurityFlags Flags which control security negotiation and |
590 | also packet signing. Authentication (may/must) | |
591 | flags (e.g. for NTLM and/or NTLMv2) may be combined with | |
592 | the signing flags. Specifying two different password | |
593 | hashing mechanisms (as "must use") on the other hand | |
594 | does not make much sense. Default flags are | |
595 | 0x07007 | |
2e655021 | 596 | (NTLM, NTLMv2 and packet signing allowed). The maximum |
254e55ed SF |
597 | allowable flags if you want to allow mounts to servers |
598 | using weaker password hashes is 0x37037 (lanman, | |
2e655021 SF |
599 | plaintext, ntlm, ntlmv2, signing allowed). Some |
600 | SecurityFlags require the corresponding menuconfig | |
601 | options to be enabled (lanman and plaintext require | |
602 | CONFIG_CIFS_WEAK_PW_HASH for example). Enabling | |
603 | plaintext authentication currently requires also | |
604 | enabling lanman authentication in the security flags | |
605 | because the cifs module only supports sending | |
606 | laintext passwords using the older lanman dialect | |
607 | form of the session setup SMB. (e.g. for authentication | |
608 | using plain text passwords, set the SecurityFlags | |
609 | to 0x30030): | |
254e55ed SF |
610 | |
611 | may use packet signing 0x00001 | |
612 | must use packet signing 0x01001 | |
613 | may use NTLM (most common password hash) 0x00002 | |
614 | must use NTLM 0x02002 | |
615 | may use NTLMv2 0x00004 | |
616 | must use NTLMv2 0x04004 | |
f6d09982 SF |
617 | may use Kerberos security 0x00008 |
618 | must use Kerberos 0x08008 | |
254e55ed SF |
619 | may use lanman (weak) password hash 0x00010 |
620 | must use lanman password hash 0x10010 | |
621 | may use plaintext passwords 0x00020 | |
622 | must use plaintext passwords 0x20020 | |
623 | (reserved for future packet encryption) 0x00040 | |
624 | ||
8426c39c JL |
625 | cifsFYI If set to non-zero value, additional debug information |
626 | will be logged to the system error log. This field | |
627 | contains three flags controlling different classes of | |
628 | debugging entries. The maximum value it can be set | |
629 | to is 7 which enables all debugging points (default 0). | |
630 | Some debugging statements are not compiled into the | |
631 | cifs kernel unless CONFIG_CIFS_DEBUG2 is enabled in the | |
632 | kernel configuration. cifsFYI may be set to one or | |
633 | nore of the following flags (7 sets them all): | |
634 | ||
635 | log cifs informational messages 0x01 | |
636 | log return codes from cifs entry points 0x02 | |
0ec54aa8 SF |
637 | log slow responses (ie which take longer than 1 second) |
638 | CONFIG_CIFS_STATS2 must be enabled in .config 0x04 | |
8426c39c JL |
639 | |
640 | ||
1da177e4 LT |
641 | traceSMB If set to one, debug information is logged to the |
642 | system error log with the start of smb requests | |
643 | and responses (default 0) | |
644 | LookupCacheEnable If set to one, inode information is kept cached | |
645 | for one second improving performance of lookups | |
646 | (default 1) | |
647 | OplockEnabled If set to one, safe distributed caching enabled. | |
648 | (default 1) | |
649 | LinuxExtensionsEnabled If set to one then the client will attempt to | |
650 | use the CIFS "UNIX" extensions which are optional | |
651 | protocol enhancements that allow CIFS servers | |
652 | to return accurate UID/GID information as well | |
653 | as support symbolic links. If you use servers | |
654 | such as Samba that support the CIFS Unix | |
655 | extensions but do not want to use symbolic link | |
656 | support and want to map the uid and gid fields | |
657 | to values supplied at mount (rather than the | |
658 | actual values, then set this to zero. (default 1) | |
60808233 SF |
659 | Experimental When set to 1 used to enable certain experimental |
660 | features (currently enables multipage writes | |
661 | when signing is enabled, the multipage write | |
662 | performance enhancement was disabled when | |
663 | signing turned on in case buffer was modified | |
664 | just before it was sent, also this flag will | |
cea21805 | 665 | be used to use the new experimental directory change |
ac683924 SF |
666 | notification code). When set to 2 enables |
667 | an additional experimental feature, "raw ntlmssp" | |
668 | session establishment support (which allows | |
669 | specifying "sec=ntlmssp" on mount). The Linux cifs | |
670 | module will use ntlmv2 authentication encapsulated | |
671 | in "raw ntlmssp" (not using SPNEGO) when | |
672 | "sec=ntlmssp" is specified on mount. | |
673 | This support also requires building cifs with | |
674 | the CONFIG_CIFS_EXPERIMENTAL configuration flag. | |
1da177e4 LT |
675 | |
676 | These experimental features and tracing can be enabled by changing flags in | |
677 | /proc/fs/cifs (after the cifs module has been installed or built into the | |
678 | kernel, e.g. insmod cifs). To enable a feature set it to 1 e.g. to enable | |
679 | tracing to the kernel message log type: | |
680 | ||
1047abc1 | 681 | echo 7 > /proc/fs/cifs/cifsFYI |
1da177e4 | 682 | |
1047abc1 SF |
683 | cifsFYI functions as a bit mask. Setting it to 1 enables additional kernel |
684 | logging of various informational messages. 2 enables logging of non-zero | |
685 | SMB return codes while 4 enables logging of requests that take longer | |
686 | than one second to complete (except for byte range lock requests). | |
687 | Setting it to 4 requires defining CONFIG_CIFS_STATS2 manually in the | |
688 | source code (typically by setting it in the beginning of cifsglob.h), | |
689 | and setting it to seven enables all three. Finally, tracing | |
690 | the start of smb requests and responses can be enabled via: | |
1da177e4 LT |
691 | |
692 | echo 1 > /proc/fs/cifs/traceSMB | |
693 | ||
75865f8c SF |
694 | Two other experimental features are under development. To test these |
695 | requires enabling CONFIG_CIFS_EXPERIMENTAL | |
1da177e4 | 696 | |
cea21805 JL |
697 | cifsacl support needed to retrieve approximated mode bits based on |
698 | the contents on the CIFS ACL. | |
1da177e4 | 699 | |
84210e91 SF |
700 | lease support: cifs will check the oplock state before calling into |
701 | the vfs to see if we can grant a lease on a file. | |
702 | ||
1da177e4 LT |
703 | DNOTIFY fcntl: needed for support of directory change |
704 | notification and perhaps later for file leases) | |
705 | ||
706 | Per share (per client mount) statistics are available in /proc/fs/cifs/Stats | |
707 | if the kernel was configured with cifs statistics enabled. The statistics | |
708 | represent the number of successful (ie non-zero return code from the server) | |
709 | SMB responses to some of the more common commands (open, delete, mkdir etc.). | |
710 | Also recorded is the total bytes read and bytes written to the server for | |
711 | that share. Note that due to client caching effects this can be less than the | |
712 | number of bytes read and written by the application running on the client. | |
713 | The statistics for the number of total SMBs and oplock breaks are different in | |
714 | that they represent all for that share, not just those for which the server | |
715 | returned success. | |
716 | ||
3d2af346 | 717 | Also note that "cat /proc/fs/cifs/DebugData" will display information about |
cea21805 | 718 | the active sessions and the shares that are mounted. |
3d2af346 SF |
719 | |
720 | Enabling Kerberos (extended security) works but requires version 1.2 or later | |
721 | of the helper program cifs.upcall to be present and to be configured in the | |
722 | /etc/request-key.conf file. The cifs.upcall helper program is from the Samba | |
723 | project(http://www.samba.org). NTLM and NTLMv2 and LANMAN support do not | |
724 | require this helper. Note that NTLMv2 security (which does not require the | |
725 | cifs.upcall helper program), instead of using Kerberos, is sufficient for | |
726 | some use cases. | |
727 | ||
be652445 SF |
728 | DFS support allows transparent redirection to shares in an MS-DFS name space. |
729 | In addition, DFS support for target shares which are specified as UNC | |
3d2af346 SF |
730 | names which begin with host names (rather than IP addresses) requires |
731 | a user space helper (such as cifs.upcall) to be present in order to | |
732 | translate host names to ip address, and the user space helper must also | |
be652445 SF |
733 | be configured in the file /etc/request-key.conf. Samba, Windows servers and |
734 | many NAS appliances support DFS as a way of constructing a global name | |
735 | space to ease network configuration and improve reliability. | |
3d2af346 SF |
736 | |
737 | To use cifs Kerberos and DFS support, the Linux keyutils package should be | |
738 | installed and something like the following lines should be added to the | |
739 | /etc/request-key.conf file: | |
740 | ||
741 | create cifs.spnego * * /usr/local/sbin/cifs.upcall %k | |
742 | create dns_resolver * * /usr/local/sbin/cifs.upcall %k | |
743 | ||
744 |