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