5 --------------------------------------------------
6 mount using the Common Internet File System (CIFS)
7 --------------------------------------------------
14 mount.cifs {service} {mount-point} [-o options]
16 This tool is part of the cifs-utils suite.
18 ``mount.cifs`` mounts a Linux CIFS filesystem. It is usually invoked
19 indirectly by the mount(8) command when using the "-t cifs"
20 option. This command only works in Linux, and the kernel must support
21 the cifs filesystem. The CIFS protocol is the successor to the SMB
22 protocol and is supported by most Windows servers and many other
23 commercial servers and Network Attached Storage appliances as well as
24 by the popular Open Source server Samba.
26 The mount.cifs utility attaches the UNC name (exported network
27 resource) specified as service (using ``//server/share`` syntax, where
28 "server" is the server name or IP address and "share" is the name of
29 the share) to the local directory mount-point.
31 Options to mount.cifs are specified as a comma-separated list of
32 ``key=value`` pairs. It is possible to send options other than those
33 listed here, assuming that the cifs filesystem kernel module
34 (``cifs.ko``) supports them. Unrecognized cifs mount options passed to
35 the cifs vfs kernel code will be logged to the kernel log.
37 ``mount.cifs`` causes the cifs vfs to launch a thread named
38 cifsd. After mounting it keeps running until the mounted resource is
39 unmounted (usually via the ``umount`` utility).
41 ``mount.cifs -V`` command displays the version of cifs mount helper.
43 ``modinfo cifs`` command displays the version of cifs module.
51 specifies the username to connect as. If this is not
52 given, then the environment variable USER is used.
54 Earlier versions of mount.cifs also allowed one to specify the
55 username in a ``user%password`` or ``workgroup/user`` or
56 ``workgroup/user%password`` to allow the password and workgroup to
57 be specified as part of the username. Support for those alternate
58 username formats is now deprecated and should no longer be
59 used. Users should use the discrete ``password=`` and ``domain=`` to
60 specify those values. While some versions of the cifs kernel module
61 accept ``user=`` as an abbreviation for this option, its use can
62 confuse the standard mount program into thinking that this is a
63 non-superuser mount. It is therefore recommended to use the full
64 ``username=`` option name.
67 specifies the CIFS password. If this option is not given then the
68 environment variable PASSWD is used. If the password is not specified
69 directly or indirectly via an argument to mount, mount.cifs will
70 prompt for a password, unless the guest option is specified.
72 Note that a password which contains the delimiter character (i.e. a
73 comma ',') will fail to be parsed correctly on the command
74 line. However, the same password defined in the PASSWD environment
75 variable or via a credentials file (see below) or entered at the
76 password prompt will be read correctly.
78 credentials=filename|cred=filename
79 specifies a file that contains a username and/or password and
80 optionally the name of the workgroup. The format of the file is::
86 This is preferred over having passwords in plaintext in a shared file,
87 such as */etc/fstab* . Be sure to protect any credentials file
91 sets the uid that will own all files or directories on the mounted
92 filesystem when the server does not provide ownership information. It
93 may be specified as either a username or a numeric uid. When not
94 specified, the default is uid 0. The mount.cifs helper must be at
95 version 1.10 or higher to support specifying the uid in non-numeric
96 form. See the section on `FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS`_
97 below for more information.
100 instructs the client to ignore any uid provided by the server for
101 files and directories and to always assign the owner to be the value
102 of the uid= option. See the section on
103 `FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS`_ below for more information.
106 sets the uid of the owner of the credentials cache. This is primarily
107 useful with ``sec=krb5``. The default is the real uid of the process
108 performing the mount. Setting this parameter directs the upcall to
109 look for a credentials cache owned by that user.
112 sets the gid that will own all files or directories on the mounted
113 filesystem when the server does not provide ownership information. It
114 may be specified as either a groupname or a numeric gid. When not
115 specified, the default is gid 0. The mount.cifs helper must be at
116 version 1.10 or higher to support specifying the gid in non-numeric
117 form. See the section on `FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS`_
118 below for more information.
121 instructs the client to ignore any gid provided by the server for
122 files and directories and to always assign the owner to be the value
123 of the gid= option. See the section on `FILE AND DIRECTORY OWNERSHIP
124 AND PERMISSIONS`_ below for more information.
127 Extract uid/gid from special SID instead of mapping it. See the
128 section on `FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS`_ below for
132 sets the port number on which the client will attempt to contact the
133 CIFS server. If this value is specified, look for an existing
134 connection with this port, and use that if one exists. If one doesn't
135 exist, try to create a new connection on that port. If that connection
136 fails, return an error. If this value isn't specified, look for an
137 existing connection on port 445 or 139. If no such connection exists,
138 try to connect on port 445 first and then port 139 if that
139 fails. Return an error if both fail.
142 When mounting to servers via port 139, specifies the RFC1001 source
143 name to use to represent the client netbios machine during the netbios
144 session initialization.
147 Similar to ``netbiosname`` except it specifies the netbios name of
148 the server instead of the client. Although rarely needed for mounting
149 to newer servers, this option is needed for mounting to some older
150 servers (such as OS/2 or Windows 98 and Windows ME) since when
151 connecting over port 139 they, unlike most newer servers, do not
152 support a default server name. A server name can be up to 15
153 characters long and is usually uppercased.
156 If the server does not support the CIFS Unix extensions this overrides
157 the default file mode.
160 If the server does not support the CIFS Unix extensions this overrides
161 the default mode for directories.
164 sets the destination IP address. This option is set automatically if
165 the server name portion of the requested UNC name can be resolved so
166 rarely needs to be specified by the user.
168 domain=arg|dom=arg|workgroup=arg
169 Sets the domain (workgroup) of the user. If no domains are given,
170 the empty domain will be used. Use ``domainauto`` to automatically
171 guess the domain of the server you are connecting to.
174 When using NTLM authentication and not providing a domain via
175 ``domain``, guess the domain from the server NTLM challenge.
176 This behavior used to be the default on kernels older than 2.6.36.
179 don't prompt for a password.
182 Charset used to convert local path names to and from Unicode. Unicode
183 is used by default for network path names if the server supports
184 it. If ``iocharset`` is not specified then the ``nls_default`` specified
185 during the local client kernel build will be used. If server does not
186 support Unicode, this parameter is unused.
195 If the CIFS Unix extensions are negotiated with the server the client
196 will attempt to set the effective uid and gid of the local process on
197 newly created files, directories, and devices (create, mkdir,
198 mknod). If the CIFS Unix Extensions are not negotiated, for newly
199 created files and directories instead of using the default uid and gid
200 specified on the the mount, cache the new file's uid and gid locally
201 which means that the uid for the file can change when the inode is
202 reloaded (or the user remounts the share).
205 The client will not attempt to set the uid and gid on on newly created
206 files, directories, and devices (create, mkdir, mknod) which will
207 result in the server setting the uid and gid to the default (usually
208 the server uid of the user who mounted the share). Letting the server
209 (rather than the client) set the uid and gid is the default. If the
210 CIFS Unix Extensions are not negotiated then the uid and gid for new
211 files will appear to be the uid (gid) of the mounter or the uid (gid)
212 parameter specified on the mount.
215 Client does permission checks (vfs_permission check of uid and gid of
216 the file against the mode and desired operation), Note that this is in
217 addition to the normal ACL check on the target machine done by the
218 server software. Client permission checking is enabled by default.
221 Client does not do permission checks. This can expose files on this
222 mount to access by other users on the local client system. It is
223 typically only needed when the server supports the CIFS Unix
224 Extensions but the UIDs/GIDs on the client and server system do not
225 match closely enough to allow access by the user doing the mount. Note
226 that this does not affect the normal ACL check on the target machine
227 done by the server software (of the server ACL against the user name
228 provided at mount time).
231 Instructs the server to maintain ownership and permissions in memory
232 that can't be stored on the server. This information can disappear
233 at any time (whenever the inode is flushed from the cache), so while
234 this may help make some applications work, it's behavior is somewhat
235 unreliable. See the section below on `FILE AND DIRECTORY OWNERSHIP
236 AND PERMISSIONS`_ for more information.
239 Cache mode. See the section below on `CACHE COHERENCY`_ for
240 details. Allowed values are:
242 - ``none`` - do not cache file data at all
243 - ``strict`` - follow the CIFS/SMB2 protocol strictly
244 - ``loose`` - allow loose caching semantics
246 The default in kernels prior to 3.7 was ``loose``. As of kernel 3.7 the
247 default is ``strict``.
250 Do not ask the server to flush on fsync().
251 Some servers perform non-buffered writes by default in which case
252 flushing is redundant. In workloads where a client is performing a
253 lot of small write + fsync combinations and where network latency is
254 much higher than the server latency, this brings a 2x performance
256 This option is also a good candidate in scenarios where we want
257 performance over consistency.
260 (default) In SMB2 and above, the client often has to open the root
261 of the share (empty path) in various places during mount, path
262 revalidation and the statfs(2) system call. This option cuts
263 redundant round trip traffic (opens and closes) by simply keeping
264 the directory handle for the root around once opened.
267 Disable caching of the share root directory handle.
270 Forward pid of a process who opened a file to any read or write
271 operation on that file. This prevent applications like wine(1) from
272 failing on read and write if we use mandatory brlock style.
275 Translate six of the seven reserved characters (not backslash, but
276 including the colon, question mark, pipe, asterik, greater than and
277 less than characters) to the remap range (above 0xF000), which also
278 allows the CIFS client to recognize files created with such characters
279 by Windows's Services for Mac. This can also be useful when mounting to
280 most versions of Samba (which also forbids creating and opening files
281 whose names contain any of these seven characters). This has no effect
282 if the server does not support Unicode on the wire. Please note that
283 the files created with ``mapchars`` mount option may not be accessible
284 if the share is mounted without that option.
287 (default) Do not translate any of these seven characters.
290 Translate reserved characters similarly to ``mapchars`` but use the
291 mapping from Microsoft "Services For Unix".
294 currently unimplemented.
297 (default) currently unimplemented.
300 The program accessing a file on the cifs mounted file system will hang
301 when the server crashes.
304 (default) The program accessing a file on the cifs mounted file system
305 will not hang when the server crashes and will return errors to the
309 Do not allow POSIX ACL operations even if server would support them.
311 The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba
312 servers version 3.0.10 and later. Setting POSIX ACLs requires enabling
313 both ``CIFS_XATTR`` and then ``CIFS_POSIX`` support in the CIFS
314 configuration options when building the cifs module. POSIX ACL support
315 can be disabled on a per mount basis by specifying ``noacl`` on mount.
318 This option is used to map CIFS/NTFS ACLs to/from Linux permission
319 bits, map SIDs to/from UIDs and GIDs, and get and set Security
322 See section on `CIFS/NTFS ACL, SID/UID/GID MAPPING, SECURITY DESCRIPTORS`_
323 for more information.
326 File access by this user shall be done with the backup intent flag
327 set. Either a name or an id must be provided as an argument, there are
330 See section `ACCESSING FILES WITH BACKUP INTENT`_ for more details.
333 File access by users who are members of this group shall be done with
334 the backup intent flag set. Either a name or an id must be provided as
335 an argument, there are no default values.
337 See section `ACCESSING FILES WITH BACKUP INTENT`_ for more details.
340 Request case insensitive path name matching (case sensitive is the default if the
344 Synonym for ``nocase``.
347 Security mode. Allowed values are:
349 - ``none`` - attempt to connection as a null user (no name)
350 - ``krb5`` - Use Kerberos version 5 authentication
351 - ``krb5i`` - Use Kerberos authentication and forcibly enable packet signing
352 - ``ntlm`` - Use NTLM password hashing
353 - ``ntlmi`` - Use NTLM password hashing and force packet signing
354 - ``ntlmv2`` - Use NTLMv2 password hashing
355 - ``ntlmv2i`` - Use NTLMv2 password hashing and force packet signing
356 - ``ntlmssp`` - Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message
357 - ``ntlmsspi`` - Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message, and force packet signing
359 The default in mainline kernel versions prior to v3.8 was
360 ``sec=ntlm``. In v3.8, the default was changed to ``sec=ntlmssp``.
362 If the server requires signing during protocol negotiation, then it
363 may be enabled automatically. Packet signing may also be enabled
364 automatically if it's enabled in */proc/fs/cifs/SecurityFlags*.
367 Request encryption at the SMB layer. The encryption algorithm used
368 is AES-128-CCM. Requires SMB3 or above (see ``vers``).
371 Connect directly to the server using SMB Direct via a RDMA
372 adapter. Requires SMB3 or above (see ``vers``).
375 Enable resilient handles. If the server supports it, keep opened
376 files across reconnections. Requires SMB2.1 (see ``vers``).
379 (default) Disable resilient handles.
382 Enable persistent handles. If the server supports it, keep opened
383 files across reconnections. Persistent handles are also valid across
384 servers in a cluster and have stronger guarantees than resilient
385 handles. Requires SMB3 or above (see ``vers``).
388 (default) Disable persistent handles.
391 Do not send byte range lock requests to the server. This is necessary
392 for certain applications that break with cifs style mandatory byte
393 range locks (and most cifs servers do not yet support requesting
394 advisory byte range locks).
397 Do not use POSIX locks even when available via unix
398 extensions. Always use cifs style mandatory locks.
401 Check cached leases locally instead of querying the server.
404 When the CIFS Unix Extensions are not negotiated, attempt to create
405 device files and fifos in a format compatible with Services for Unix
406 (SFU). In addition retrieve bits 10-12 of the mode via the
407 ``SETFILEBITS`` extended attribute (as SFU does). In the future the
408 bottom 9 bits of the mode mode also will be emulated using queries of
409 the security descriptor (ACL). [NB: requires version 1.39 or later of
410 the CIFS VFS. To recognize symlinks and be able to create symlinks in
411 an SFU interoperable form requires version 1.40 or later of the CIFS
415 Enable support for Minshall+French symlinks (see
416 `http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks <http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks>`_). This
417 option is ignored when specified together with the ``sfu``
418 option. Minshall+French symlinks are used even if the server supports
419 the CIFS Unix Extensions.
422 sets the interval at which echo requests are sent to the server on an
423 idling connection. This setting also affects the time required for a
424 connection to an unresponsive server to timeout. Here n is the echo
425 interval in seconds. The reconnection happens at twice the value of the
426 echo_interval set for an unresponsive server.
427 If this option is not given then the default value of 60 seconds is used.
428 The minimum tunable value is 1 second and maximum can go up to 600 seconds.
431 Use inode numbers (unique persistent file identifiers) returned by the
432 server instead of automatically generating temporary inode numbers on
433 the client. Although server inode numbers make it easier to spot
434 hardlinked files (as they will have the same inode numbers) and inode
435 numbers may be persistent (which is useful for some software), the
436 server does not guarantee that the inode numbers are unique if
437 multiple server side mounts are exported under a single share (since
438 inode numbers on the servers might not be unique if multiple
439 filesystems are mounted under the same shared higher level
440 directory). Note that not all servers support returning server inode
441 numbers, although those that support the CIFS Unix Extensions, and
442 Windows 2000 and later servers typically do support this (although not
443 necessarily on every local server filesystem). Parameter has no effect
444 if the server lacks support for returning inode numbers or
445 equivalent. This behavior is enabled by default.
448 Client generates inode numbers itself rather than using the actual
449 ones from the server.
451 See section `INODE NUMBERS`_ for more information.
454 (default) Enable Unix Extensions for this mount. Requires CIFS
455 (vers=1.0) or SMB3.1.1 (vers=3.1.1) and a server supporting them.
458 Disable the Unix Extensions for this mount. This can be useful in
459 order to turn off multiple settings at once. This includes POSIX acls,
460 POSIX locks, POSIX paths, symlink support and retrieving
461 uids/gids/mode from the server. This can also be useful to work around
462 a bug in a server that supports Unix Extensions.
464 See section `INODE NUMBERS`_ for more information.
467 Do not allow getfattr/setfattr to get/set xattrs, even if server would
468 support it otherwise. The default is for xattr support to be enabled.
471 Do not follow Distributed FileSystem referrals. IO on a file not
472 stored on the server will fail instead of connecting to the target
473 server transparently.
476 Use fixed size for kernel recv/send socket buffers.
479 Do not try to reuse sockets if the system is already connected to
480 the server via an existing mount point. This will make the client
481 always make a new connection to the server no matter what he is
482 already connected to.
485 Send data on the socket using non blocking operations (MSG_DONTWAIT flag).
488 Maximum amount of data that the kernel will request in a read request
489 in bytes. Prior to kernel 3.2.0, the default was 16k, and the maximum
490 size was limited by the ``CIFSMaxBufSize`` module parameter. As of
491 kernel 3.2.0, the behavior varies according to whether POSIX
492 extensions are enabled on the mount and the server supports large
493 POSIX reads. If they are, then the default is 1M, and the maximum is
494 16M. If they are not supported by the server, then the default is 60k
495 and the maximum is around 127k. The reason for the 60k is because it's
496 the maximum size read that windows servers can fill. Note that this
497 value is a maximum, and the client may settle on a smaller size to
498 accommodate what the server supports. In kernels prior to 3.2.0, no
499 negotiation is performed.
502 Maximum amount of data that the kernel will send in a write request in
503 bytes. Prior to kernel 3.0.0, the default and maximum was 57344 (14 \*
504 4096 pages). As of 3.0.0, the default depends on whether the client
505 and server negotiate large writes via POSIX extensions. If they do,
506 then the default is 1M, and the maximum allowed is 16M. If they do
507 not, then the default is 65536 and the maximum allowed is 131007. Note
508 that this value is just a starting point for negotiation in 3.0.0 and
509 up. The client and server may negotiate this size downward according
510 to the server's capabilities. In kernels prior to 3.0.0, no
511 negotiation is performed. It can end up with an existing superblock if
512 this value isn't specified or it's greater or equal than the existing
516 Maximum credits the SMB2 client can have. Default is 32000. Must be
517 set to a number between 20 and 60000.
520 Enable local disk caching using FS-Cache for CIFS. This option could
521 be useful to improve performance on a slow link, heavily loaded server
522 and/or network where reading from the disk is faster than reading from
523 the server (over the network). This could also impact the scalability
524 positively as the number of calls to the server are reduced. But, be
525 warned that local caching is not suitable for all workloads, for e.g.,
526 read-once type workloads. So, you need to consider carefully the
527 situation/workload before using this option. Currently, local disk
528 caching is enabled for CIFS files opened as read-only.
530 **NOTE**: This feature is available only in the recent kernels that
531 have been built with the kernel config option
532 ``CONFIG_CIFS_FSCACHE``. You also need to have ``cachefilesd``
533 daemon installed and running to make the cache operational.
536 Map user accesses to individual credentials when accessing the
537 server. By default, CIFS mounts only use a single set of user
538 credentials (the mount credentials) when accessing a share. With this
539 option, the client instead creates a new session with the server using
540 the user's credentials whenever a new user accesses the mount.
541 Further accesses by that user will also use those credentials. Because
542 the kernel cannot prompt for passwords, multiuser mounts are limited
543 to mounts using ``sec=`` options that don't require passwords.
545 With this change, it's feasible for the server to handle permissions
546 enforcement, so this option also implies ``noperm`` . Furthermore, when
547 unix extensions aren't in use and the administrator has not overridden
548 ownership using the ``uid=`` or ``gid=`` options, ownership of files is
549 presented as the current user accessing the share.
552 The time (in seconds) that the CIFS client caches attributes of a file or
553 directory before it requests attribute information from a server. During this
554 period the changes that occur on the server remain undetected until the client
555 checks the server again.
557 By default, the attribute cache timeout is set to 1 second. This means
558 more frequent on-the-wire calls to the server to check whether
559 attributes have changed which could impact performance. With this
560 option users can make a tradeoff between performance and cache
561 metadata correctness, depending on workload needs. Shorter timeouts
562 mean better cache coherency, but frequent increased number of calls to
563 the server. Longer timeouts mean a reduced number of calls to the
564 server but looser cache coherency. The ``actimeo`` value is a positive
565 integer that can hold values between 0 and a maximum value of 2^30 \*
566 HZ (frequency of timer interrupt) setting.
569 If unix extensions are enabled on a share, then the client will
570 typically allow filenames to include any character besides '/' in a
571 pathname component, and will use forward slashes as a pathname
572 delimiter. This option prevents the client from attempting to
573 negotiate the use of posix-style pathnames to the server.
576 Inverse of ``noposixpaths`` .
579 It's possible to mount a subdirectory of a share. The preferred way to
580 do this is to append the path to the UNC when mounting. However, it's
581 also possible to do the same by setting this option and providing the
585 SMB protocol version. Allowed values are:
587 - 1.0 - The classic CIFS/SMBv1 protocol.
588 - 2.0 - The SMBv2.002 protocol. This was initially introduced in
589 Windows Vista Service Pack 1, and Windows Server 2008. Note that
590 the initial release version of Windows Vista spoke a slightly
591 different dialect (2.000) that is not supported.
592 - 2.1 - The SMBv2.1 protocol that was introduced in Microsoft Windows 7 and Windows Server 2008R2.
593 - 3.0 - The SMBv3.0 protocol that was introduced in Microsoft Windows 8 and Windows Server 2012.
594 - 3.02 - The SMBv3.0.2 protocol that was introduced in Microsoft Windows 8.1 and Windows Server 2012R2.
595 - 3.1.1 or 3.11 - The SMBv3.1.1 protocol that was introduced in Microsoft Windows Server 2016.
596 - 3 - The SMBv3.0 protocol version and above.
598 Note too that while this option governs the protocol version used, not
599 all features of each version are available.
601 The default since v4.13.5 is for the client and server to negotiate
602 the highest possible version greater than or equal to ``2.1``. In
603 kernels prior to v4.13, the default was ``1.0``. For kernels
604 between v4.13 and v4.13.5 the default is ``3.0``.
607 Print additional debugging information for the mount. Note that this
608 parameter must be specified before the ``-o`` . For example::
610 mount -t cifs //server/share /mnt --verbose -o user=username
613 *********************************
614 SERVICE FORMATTING AND DELIMITERS
615 *********************************
617 It's generally preferred to use forward slashes (/) as a delimiter in
618 service names. They are considered to be the "universal delimiter"
619 since they are generally not allowed to be embedded within path
620 components on Windows machines and the client can convert them to
621 backslashes (\\) unconditionally. Conversely, backslash characters are
622 allowed by POSIX to be part of a path component, and can't be
623 automatically converted in the same way.
625 ``mount.cifs`` will attempt to convert backslashes to forward slashes
626 where it's able to do so, but it cannot do so in any path component
627 following the sharename.
635 When Unix Extensions are enabled, we use the actual inode number
636 provided by the server in response to the POSIX calls as an inode
639 When Unix Extensions are disabled and ``serverino`` mount option is
640 enabled there is no way to get the server inode number. The client
641 typically maps the server-assigned ``UniqueID`` onto an inode number.
643 Note that the ``UniqueID`` is a different value from the server inode
644 number. The ``UniqueID`` value is unique over the scope of the entire
645 server and is often greater than 2 power 32. This value often makes
646 programs that are not compiled with LFS (Large File Support), to
647 trigger a glibc ``EOVERFLOW`` error as this won't fit in the target
648 structure field. It is strongly recommended to compile your programs
649 with LFS support (i.e. with ``-D_FILE_OFFSET_BITS=64``) to prevent this
650 problem. You can also use ``noserverino`` mount option to generate
651 inode numbers smaller than 2 power 32 on the client. But you may not
652 be able to detect hardlinks properly.
658 With a network filesystem such as CIFS or NFS, the client must contend
659 with the fact that activity on other clients or the server could
660 change the contents or attributes of a file without the client being
661 aware of it. One way to deal with such a problem is to mandate that
662 all file accesses go to the server directly. This is performance
663 prohibitive however, so most protocols have some mechanism to allow
664 the client to cache data locally.
666 The CIFS protocol mandates (in effect) that the client should not
667 cache file data unless it holds an opportunistic lock (aka oplock) or
668 a lease. Both of these entities allow the client to guarantee certain
669 types of exclusive access to a file so that it can access its contents
670 without needing to continually interact with the server. The server
671 will call back the client when it needs to revoke either of them and
672 allow the client a certain amount of time to flush any cached data.
674 The cifs client uses the kernel's pagecache to cache file data. Any
675 I/O that's done through the pagecache is generally page-aligned. This
676 can be problematic when combined with byte-range locks as Windows'
677 locking is mandatory and can block reads and writes from occurring.
679 ``cache=none`` means that the client never utilizes the cache for
680 normal reads and writes. It always accesses the server directly to
681 satisfy a read or write request.
683 ``cache=strict`` means that the client will attempt to follow the
684 CIFS/SMB2 protocol strictly. That is, the cache is only trusted when
685 the client holds an oplock. When the client does not hold an oplock,
686 then the client bypasses the cache and accesses the server directly to
687 satisfy a read or write request. By doing this, the client avoids
688 problems with byte range locks. Additionally, byte range locks are
689 cached on the client when it holds an oplock and are "pushed" to the
690 server when that oplock is recalled.
692 ``cache=loose`` allows the client to use looser protocol semantics
693 which can sometimes provide better performance at the expense of cache
694 coherency. File access always involves the pagecache. When an oplock
695 or lease is not held, then the client will attempt to flush the cache
696 soon after a write to a file. Note that that flush does not
697 necessarily occur before a write system call returns.
699 In the case of a read without holding an oplock, the client will
700 attempt to periodically check the attributes of the file in order to
701 ascertain whether it has changed and the cache might no longer be
702 valid. This mechanism is much like the one that NFSv2/3 use for cache
703 coherency, but it particularly problematic with CIFS. Windows is
704 quite "lazy" with respect to updating the ``LastWriteTime`` field that
705 the client uses to verify this. The effect is that ``cache=loose`` can
706 cause data corruption when multiple readers and writers are working on
709 Because of this, when multiple clients are accessing the same set of
710 files, then ``cache=strict`` is recommended. That helps eliminate
711 problems with cache coherency by following the CIFS/SMB2 protocols
714 Note too that no matter what caching model is used, the client will
715 always use the pagecache to handle mmap'ed files. Writes to mmap'ed
716 files are only guaranteed to be flushed to the server when msync() is
717 called, or on close().
719 The default in kernels prior to 3.7 was ``loose``. As of 3.7, the
720 default is ``strict``.
722 ********************************************************
723 CIFS/NTFS ACL, SID/UID/GID MAPPING, SECURITY DESCRIPTORS
724 ********************************************************
726 This option is used to work with file objects which posses Security
727 Descriptors and CIFS/NTFS ACL instead of UID, GID, file permission
728 bits, and POSIX ACL as user authentication model. This is the most
729 common authentication model for CIFS servers and is the one used by
732 Support for this requires both CIFS_XATTR and CIFS_ACL support in the
733 CIFS configuration options when building the cifs module.
735 A CIFS/NTFS ACL is mapped to file permission bits using an algorithm
736 specified in the following Microsoft TechNet document:
738 `http://technet.microsoft.com/en-us/library/bb463216.aspx <http://technet.microsoft.com/en-us/library/bb463216.aspx>`_
740 In order to map SIDs to/from UIDs and GIDs, the following is required:
742 - a kernel upcall to the ``cifs.idmap`` utility set up via request-key.conf(5)
743 - winbind support configured via nsswitch.conf(5) and smb.conf(5)
745 Please refer to the respective manpages of cifs.idmap(8) and
746 winbindd(8) for more information.
748 Security descriptors for a file object can be retrieved and set
749 directly using extended attribute named ``system.cifs_acl``. The
750 security descriptors presented via this interface are "raw" blobs of
751 data and need a userspace utility to either parse and format or to
752 assemble it such as getcifsacl(1) and setcifsacl(1)
755 Some of the things to consider while using this mount option:
757 - There may be an increased latency when handling metadata due to
758 additional requests to get and set security descriptors.
759 - The mapping between a CIFS/NTFS ACL and POSIX file permission bits
760 is imperfect and some ACL information may be lost in the
762 - If either upcall to cifs.idmap is not setup correctly or winbind is
763 not configured and running, ID mapping will fail. In that case uid
764 and gid will default to either to those values of the share or to
765 the values of uid and/or gid mount options if specified.
767 **********************************
768 ACCESSING FILES WITH BACKUP INTENT
769 **********************************
771 For an user on the server, desired access to a file is determined by
772 the permissions and rights associated with that file. This is
773 typically accomplished using ownership and ACL. For a user who does
774 not have access rights to a file, it is still possible to access that
775 file for a specific or a targeted purpose by granting special rights.
776 One of the specific purposes is to access a file with the intent to
777 either backup or restore i.e. backup intent. The right to access a
778 file with the backup intent can typically be granted by making that
779 user a part of the built-in group *Backup Operators*. Thus, when
780 this user attempts to open a file with the backup intent, open request
781 is sent by setting the bit ``FILE_OPEN_FOR_BACKUP_INTENT`` as one of
782 the ``CreateOptions``.
784 As an example, on a Windows server, a user named *testuser*, cannot open
785 this file with such a security descriptor::
791 ACL:Administrator:ALLOWED/0x0/FULL
793 But the user *testuser*, if it becomes part of the *Backup Operators*
794 group, can open the file with the backup intent.
796 Any user on the client side who can authenticate as such a user on the
797 server, can access the files with the backup intent. But it is
798 desirable and preferable for security reasons amongst many, to
799 restrict this special right.
801 The mount option ``backupuid`` is used to restrict this special right
802 to a user which is specified by either a name or an id. The mount
803 option ``backupgid`` is used to restrict this special right to the
804 users in a group which is specified by either a name or an id. Only
805 users matching either backupuid or backupgid shall attempt to access
806 files with backup intent. These two mount options can be used
809 ********************************************
810 FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS
811 ********************************************
813 The core CIFS protocol does not provide unix ownership information or
814 mode for files and directories. Because of this, files and directories
815 will generally appear to be owned by whatever values the ``uid=`` or
816 ``gid=`` options are set, and will have permissions set to the default
817 ``file_mode`` and ``dir_mode`` for the mount. Attempting to change these
818 values via chmod/chown will return success but have no effect.
820 When the client and server negotiate unix extensions, files and
821 directories will be assigned the uid, gid, and mode provided by the
822 server. Because CIFS mounts are generally single-user, and the same
823 credentials are used no matter what user accesses the mount, newly
824 created files and directories will generally be given ownership
825 corresponding to whatever credentials were used to mount the share.
827 If the uid's and gid's being used do not match on the client and
828 server, the ``forceuid`` and ``forcegid`` options may be helpful. Note
829 however, that there is no corresponding option to override the
830 mode. Permissions assigned to a file when ``forceuid`` or ``forcegid``
831 are in effect may not reflect the the real permissions.
833 When unix extensions are not negotiated, it's also possible to emulate
834 them locally on the server using the ``dynperm`` mount option. When
835 this mount option is in effect, newly created files and directories
836 will receive what appear to be proper permissions. These permissions
837 are not stored on the server however and can disappear at any time in
838 the future (subject to the whims of the kernel flushing out the inode
839 cache). In general, this mount option is discouraged.
841 It's also possible to override permission checking on the client
842 altogether via the ``noperm`` option. Server-side permission checks
843 cannot be overridden. The permission checks done by the server will
844 always correspond to the credentials used to mount the share, and not
845 necessarily to the user who is accessing the share.
847 *********************
848 ENVIRONMENT VARIABLES
849 *********************
851 The variable ``USER`` may contain the username of the person to be used
852 to authenticate to the server. The variable can be used to set both
853 username and password by using the format ``username%password``.
855 The variable ``PASSWD`` may contain the password of the person using
858 The variable ``PASSWD_FILE`` may contain the pathname of a file to read
859 the password from. A single line of input is read and used as the
866 This command may be used only by root, unless installed setuid, in
867 which case the noexec and nosuid mount flags are enabled. When
868 installed as a setuid program, the program follows the conventions set
869 forth by the mount program for user mounts, with the added restriction
870 that users must be able to chdir() into the mountpoint prior to the
871 mount in order to be able to mount onto it.
873 Some samba client tools like smbclient(8) honour client-side
874 configuration parameters present in *smb.conf*. Unlike those client
875 tools, ``mount.cifs`` ignores *smb.conf* completely.
881 The primary mechanism for making configuration changes and for reading
882 debug information for the cifs vfs is via the Linux /proc
883 filesystem. In the directory */proc/fs/cifs* are various
884 configuration files and pseudo files which can display debug
885 information. There are additional startup options such as maximum
886 buffer size and number of buffers which only may be set when the
887 kernel cifs vfs (cifs.ko module) is loaded. These can be seen by
888 running the ``modinfo`` utility against the file cifs.ko which will
889 list the options that may be passed to cifs during module installation
890 (device driver load). For more information see the kernel file
897 Mounting using the CIFS URL specification is currently not supported.
899 The credentials file does not handle usernames or passwords with
902 Note that the typical response to a bug report is a suggestion to try
903 the latest version first. So please try doing that first, and always
904 include which versions you use of relevant software when reporting
905 bugs (minimum: mount.cifs (try ``mount.cifs -V``), kernel (see
906 */proc/version*) and server type you are trying to contact.
912 This man page is correct for version 1.74 of the cifs vfs filesystem
913 (roughly Linux kernel 3.0).
919 cifs.upcall(8), getcifsacl(1), setcifsacl(1)
921 *Documentation/filesystems/cifs.txt* and *fs/cifs/README* in the
922 Linux kernel source tree may contain additional options and
931 The maintainer of the Linux cifs vfs and the userspace tool mount.cifs
932 is Steve French. The Linux CIFS Mailing list is the preferred place to
933 ask questions regarding these programs.
git.samba.org / cifs-utils.git / blob