Manual section: | 8 |
---|
mount.cifs {service} {mount-point} [-o options]
This tool is part of the cifs-utils suite.
mount.cifs
mounts a Linux CIFS filesystem. It is usually invoked
indirectly by the mount(8) command when using the "-t cifs"
option. This command only works in Linux, and the kernel must support
the cifs filesystem. The CIFS protocol is the successor to the SMB
protocol and is supported by most Windows servers and many other
commercial servers and Network Attached Storage appliances as well as
by the popular Open Source server Samba.
The mount.cifs utility attaches the UNC name (exported network
resource) specified as service (using //server/share
syntax, where
"server" is the server name or IP address and "share" is the name of
the share) to the local directory mount-point.
Options to mount.cifs are specified as a comma-separated list of
key=value
pairs. It is possible to send options other than those
listed here, assuming that the cifs filesystem kernel module
(cifs.ko
) supports them. Unrecognized cifs mount options passed to
the cifs vfs kernel code will be logged to the kernel log.
mount.cifs
causes the cifs vfs to launch a thread named
cifsd. After mounting it keeps running until the mounted resource is
unmounted (usually via the umount
utility).
mount.cifs -V
command displays the version of cifs mount helper.
modinfo cifs
command displays the version of cifs module.
specifies the username to connect as. If this is not given, then the environment variable USER is used.
Earlier versions of mount.cifs also allowed one to specify the
username in a user%password
or workgroup/user
or
workgroup/user%password
to allow the password and workgroup to
be specified as part of the username. Support for those alternate
username formats is now deprecated and should no longer be
used. Users should use the discrete password=
and domain=
to
specify those values. While some versions of the cifs kernel module
accept user=
as an abbreviation for this option, its use can
confuse the standard mount program into thinking that this is a
non-superuser mount. It is therefore recommended to use the full
username=
option name.
specifies the CIFS password. If this option is not given then the environment variable PASSWD is used. If the password is not specified directly or indirectly via an argument to mount, mount.cifs will prompt for a password, unless the guest option is specified.
Note that a password which contains the delimiter character (i.e. a comma ',') will fail to be parsed correctly on the command line. However, the same password defined in the PASSWD environment variable or via a credentials file (see below) or entered at the password prompt will be read correctly.
specifies a file that contains a username and/or password and optionally the name of the workgroup. The format of the file is:
username=value password=value domain=value
This is preferred over having passwords in plaintext in a shared file,
such as /etc/fstab
. Be sure to protect any credentials file
properly.
sec=krb5
. The default is the real uid of the process
performing the mount. Setting this parameter directs the upcall to
look for a credentials cache owned by that user.servernetbiosname
iocharset
is not specified then the nls_default
specified
during the local client kernel build will be used. If server does not
support Unicode, this parameter is unused.Cache mode. See the section below on CACHE COHERENCY for details. Allowed values are:
none
- do not cache file data at allstrict
- follow the CIFS/SMB2 protocol strictlyloose
- allow loose caching semanticsThe default in kernels prior to 3.7 was loose
. As of kernel 3.7 the
default is strict
.
Do not do inode data caching on files opened on this mount. This
precludes mmaping files on this mount. In some cases with fast
networks and little or no caching benefits on the client (e.g. when
the application is doing large sequential reads bigger than page size
without rereading the same data) this can provide better performance
than the default behavior which caches reads (readahead) and writes
(writebehind) through the local Linux client pagecache if oplock
(caching token) is granted and held. Note that direct allows write
operations larger than page size to be sent to the server. On some
kernels this requires the cifs.ko module to be built with the
CIFS_EXPERIMENTAL
configure option.
This option is will be deprecated in 3.7. Users should use
cache=none
instead on more recent kernels.
Use for switching on strict cache mode. In this mode the client reads from the cache all the time it has Oplock Level II , otherwise - read from the server. As for write - the client stores a data in the cache in Exclusive Oplock case, otherwise - write directly to the server.
This option is will be deprecated in 3.7. Users should use
cache=strict
instead on more recent kernels.
mapchars
mount option may not be accessible
if the share is mounted without that option.Do not allow POSIX ACL operations even if server would support them.
The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to Samba
servers version 3.0.10 and later. Setting POSIX ACLs requires enabling
both CIFS_XATTR
and then CIFS_POSIX
support in the CIFS
configuration options when building the cifs module. POSIX ACL support
can be disabled on a per mount basis by specifying noacl
on mount.
This option is used to map CIFS/NTFS ACLs to/from Linux permission bits, map SIDs to/from UIDs and GIDs, and get and set Security Descriptors.
See section on CIFS/NTFS ACL, SID/UID/GID MAPPING, SECURITY DESCRIPTORS for more information.
File access by this user shall be done with the backup intent flag set. Either a name or an id must be provided as an argument, there are no default values.
See section ACCESSING FILES WITH BACKUP INTENT for more details.
File access by users who are members of this group shall be done with the backup intent flag set. Either a name or an id must be provided as an argument, there are no default values.
See section ACCESSING FILES WITH BACKUP INTENT for more details.
nocase
.Security mode. Allowed values are:
none
- attempt to connection as a null user (no name)krb5
- Use Kerberos version 5 authenticationkrb5i
- Use Kerberos authentication and forcibly enable packet signingntlm
- Use NTLM password hashingntlmi
- Use NTLM password hashing and force packet signingntlmv2
- Use NTLMv2 password hashingntlmv2i
- Use NTLMv2 password hashing and force packet signingntlmssp
- Use NTLMv2 password hashing encapsulated in Raw NTLMSSP messagentlmsspi
- Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message, and force packet signingThe default in mainline kernel versions prior to v3.8 was
sec=ntlm
. In v3.8, the default was changed to sec=ntlmssp
.
If the server requires signing during protocol negotiation, then it may be enabled automatically. Packet signing may also be enabled automatically if it's enabled in /proc/fs/cifs/SecurityFlags.
SETFILEBITS
extended attribute (as SFU does). In the future the
bottom 9 bits of the mode mode also will be emulated using queries of
the security descriptor (ACL). [NB: requires version 1.39 or later of
the CIFS VFS. To recognize symlinks and be able to create symlinks in
an SFU interoperable form requires version 1.40 or later of the CIFS
VFS kernel module.sfu
option. Minshall+French symlinks are used even if the server supports
the CIFS Unix Extensions.Client generates inode numbers itself rather than using the actual ones from the server.
See section INODE NUMBERS for more information.
Disable the CIFS Unix Extensions for this mount. This can be useful in order to turn off multiple settings at once. This includes POSIX acls, POSIX locks, POSIX paths, symlink support and retrieving uids/gids/mode from the server. This can also be useful to work around a bug in a server that supports Unix Extensions.
See section INODE NUMBERS for more information.
CIFSMaxBufSize
module parameter. As of
kernel 3.2.0, the behavior varies according to whether POSIX
extensions are enabled on the mount and the server supports large
POSIX reads. If they are, then the default is 1M, and the maximum is
16M. If they are not supported by the server, then the default is 60k
and the maximum is around 127k. The reason for the 60k is because it's
the maximum size read that windows servers can fill. Note that this
value is a maximum, and the client may settle on a smaller size to
accommodate what the server supports. In kernels prior to 3.2.0, no
negotiation is performed.Enable local disk caching using FS-Cache for CIFS. This option could be useful to improve performance on a slow link, heavily loaded server and/or network where reading from the disk is faster than reading from the server (over the network). This could also impact the scalability positively as the number of calls to the server are reduced. But, be warned that local caching is not suitable for all workloads, for e.g., read-once type workloads. So, you need to consider carefully the situation/workload before using this option. Currently, local disk caching is enabled for CIFS files opened as read-only.
NOTE: This feature is available only in the recent kernels that
have been built with the kernel config option
CONFIG_CIFS_FSCACHE
. You also need to have cachefilesd
daemon installed and running to make the cache operational.
Map user accesses to individual credentials when accessing the
server. By default, CIFS mounts only use a single set of user
credentials (the mount credentials) when accessing a share. With this
option, the client instead creates a new session with the server using
the user's credentials whenever a new user accesses the mount.
Further accesses by that user will also use those credentials. Because
the kernel cannot prompt for passwords, multiuser mounts are limited
to mounts using sec=
options that don't require passwords.
With this change, it's feasible for the server to handle permissions
enforcement, so this option also implies noperm
. Furthermore, when
unix extensions aren't in use and the administrator has not overridden
ownership using the uid=
or gid=
options, ownership of files is
presented as the current user accessing the share.
The time (in seconds) that the CIFS client caches attributes of a file or directory before it requests attribute information from a server. During this period the changes that occur on the server remain undetected until the client checks the server again.
By default, the attribute cache timeout is set to 1 second. This means
more frequent on-the-wire calls to the server to check whether
attributes have changed which could impact performance. With this
option users can make a tradeoff between performance and cache
metadata correctness, depending on workload needs. Shorter timeouts
mean better cache coherency, but frequent increased number of calls to
the server. Longer timeouts mean a reduced number of calls to the
server but looser cache coherency. The actimeo
value is a positive
integer that can hold values between 0 and a maximum value of 2^30 *
HZ (frequency of timer interrupt) setting.
noposixpaths
.SMB protocol version. Allowed values are:
Note too that while this option governs the protocol version used, not all features of each version are available.
The default since v4.13.5 is for the client and server to negotiate
the highest possible version greater than or equal to 2.1
. In
kernels prior to v4.13, the default was 1.0
. For kernels
between v4.13 and v4.13.5 the default is 3.0
.
--verbose | Print additional debugging information for the mount. Note that this
parameter must be specified before the mount -t cifs //server/share /mnt --verbose -o user=username |
It's generally preferred to use forward slashes (/) as a delimiter in service names. They are considered to be the "universal delimiter" since they are generally not allowed to be embedded within path components on Windows machines and the client can convert them to backslashes () unconditionally. Conversely, backslash characters are allowed by POSIX to be part of a path component, and can't be automatically converted in the same way.
mount.cifs
will attempt to convert backslashes to forward slashes
where it's able to do so, but it cannot do so in any path component
following the sharename.
When Unix Extensions are enabled, we use the actual inode number provided by the server in response to the POSIX calls as an inode number.
When Unix Extensions are disabled and serverino
mount option is
enabled there is no way to get the server inode number. The client
typically maps the server-assigned UniqueID
onto an inode number.
Note that the UniqueID
is a different value from the server inode
number. The UniqueID
value is unique over the scope of the entire
server and is often greater than 2 power 32. This value often makes
programs that are not compiled with LFS (Large File Support), to
trigger a glibc EOVERFLOW
error as this won't fit in the target
structure field. It is strongly recommended to compile your programs
with LFS support (i.e. with -D_FILE_OFFSET_BITS=64
) to prevent this
problem. You can also use noserverino
mount option to generate
inode numbers smaller than 2 power 32 on the client. But you may not
be able to detect hardlinks properly.
With a network filesystem such as CIFS or NFS, the client must contend with the fact that activity on other clients or the server could change the contents or attributes of a file without the client being aware of it. One way to deal with such a problem is to mandate that all file accesses go to the server directly. This is performance prohibitive however, so most protocols have some mechanism to allow the client to cache data locally.
The CIFS protocol mandates (in effect) that the client should not cache file data unless it holds an opportunistic lock (aka oplock) or a lease. Both of these entities allow the client to guarantee certain types of exclusive access to a file so that it can access its contents without needing to continually interact with the server. The server will call back the client when it needs to revoke either of them and allow the client a certain amount of time to flush any cached data.
The cifs client uses the kernel's pagecache to cache file data. Any I/O that's done through the pagecache is generally page-aligned. This can be problematic when combined with byte-range locks as Windows' locking is mandatory and can block reads and writes from occurring.
cache=none
means that the client never utilizes the cache for
normal reads and writes. It always accesses the server directly to
satisfy a read or write request.
cache=strict
means that the client will attempt to follow the
CIFS/SMB2 protocol strictly. That is, the cache is only trusted when
the client holds an oplock. When the client does not hold an oplock,
then the client bypasses the cache and accesses the server directly to
satisfy a read or write request. By doing this, the client avoids
problems with byte range locks. Additionally, byte range locks are
cached on the client when it holds an oplock and are "pushed" to the
server when that oplock is recalled.
cache=loose
allows the client to use looser protocol semantics
which can sometimes provide better performance at the expense of cache
coherency. File access always involves the pagecache. When an oplock
or lease is not held, then the client will attempt to flush the cache
soon after a write to a file. Note that that flush does not
necessarily occur before a write system call returns.
In the case of a read without holding an oplock, the client will
attempt to periodically check the attributes of the file in order to
ascertain whether it has changed and the cache might no longer be
valid. This mechanism is much like the one that NFSv2/3 use for cache
coherency, but it particularly problematic with CIFS. Windows is
quite "lazy" with respect to updating the LastWriteTime
field that
the client uses to verify this. The effect is that cache=loose
can
cause data corruption when multiple readers and writers are working on
the same files.
Because of this, when multiple clients are accessing the same set of
files, then cache=strict
is recommended. That helps eliminate
problems with cache coherency by following the CIFS/SMB2 protocols
more strictly.
Note too that no matter what caching model is used, the client will always use the pagecache to handle mmap'ed files. Writes to mmap'ed files are only guaranteed to be flushed to the server when msync() is called, or on close().
The default in kernels prior to 3.7 was loose
. As of 3.7, the
default is strict
.
This option is used to work with file objects which posses Security Descriptors and CIFS/NTFS ACL instead of UID, GID, file permission bits, and POSIX ACL as user authentication model. This is the most common authentication model for CIFS servers and is the one used by Windows.
Support for this requires both CIFS_XATTR and CIFS_ACL support in the CIFS configuration options when building the cifs module.
A CIFS/NTFS ACL is mapped to file permission bits using an algorithm specified in the following Microsoft TechNet document:
http://technet.microsoft.com/en-us/library/bb463216.aspx
In order to map SIDs to/from UIDs and GIDs, the following is required:
cifs.idmap
utility set up via request-key.conf(5)Please refer to the respective manpages of cifs.idmap(8) and winbindd(8) for more information.
Security descriptors for a file object can be retrieved and set
directly using extended attribute named system.cifs_acl
. The
security descriptors presented via this interface are "raw" blobs of
data and need a userspace utility to either parse and format or to
assemble it such as getcifsacl(1) and setcifsacl(1)
respectively.
Some of the things to consider while using this mount option:
For an user on the server, desired access to a file is determined by
the permissions and rights associated with that file. This is
typically accomplished using ownership and ACL. For a user who does
not have access rights to a file, it is still possible to access that
file for a specific or a targeted purpose by granting special rights.
One of the specific purposes is to access a file with the intent to
either backup or restore i.e. backup intent. The right to access a
file with the backup intent can typically be granted by making that
user a part of the built-in group Backup Operators. Thus, when
this user attempts to open a file with the backup intent, open request
is sent by setting the bit FILE_OPEN_FOR_BACKUP_INTENT
as one of
the CreateOptions
.
As an example, on a Windows server, a user named testuser, cannot open this file with such a security descriptor:
REVISION:0x1 CONTROL:0x9404 OWNER:Administrator GROUP:Domain Users ACL:Administrator:ALLOWED/0x0/FULL
But the user testuser, if it becomes part of the Backup Operators group, can open the file with the backup intent.
Any user on the client side who can authenticate as such a user on the server, can access the files with the backup intent. But it is desirable and preferable for security reasons amongst many, to restrict this special right.
The mount option backupuid
is used to restrict this special right
to a user which is specified by either a name or an id. The mount
option backupgid
is used to restrict this special right to the
users in a group which is specified by either a name or an id. Only
users matching either backupuid or backupgid shall attempt to access
files with backup intent. These two mount options can be used
together.
The core CIFS protocol does not provide unix ownership information or
mode for files and directories. Because of this, files and directories
will generally appear to be owned by whatever values the uid=
or
gid=
options are set, and will have permissions set to the default
file_mode
and dir_mode
for the mount. Attempting to change these
values via chmod/chown will return success but have no effect.
When the client and server negotiate unix extensions, files and directories will be assigned the uid, gid, and mode provided by the server. Because CIFS mounts are generally single-user, and the same credentials are used no matter what user accesses the mount, newly created files and directories will generally be given ownership corresponding to whatever credentials were used to mount the share.
If the uid's and gid's being used do not match on the client and
server, the forceuid
and forcegid
options may be helpful. Note
however, that there is no corresponding option to override the
mode. Permissions assigned to a file when forceuid
or forcegid
are in effect may not reflect the the real permissions.
When unix extensions are not negotiated, it's also possible to emulate
them locally on the server using the dynperm
mount option. When
this mount option is in effect, newly created files and directories
will receive what appear to be proper permissions. These permissions
are not stored on the server however and can disappear at any time in
the future (subject to the whims of the kernel flushing out the inode
cache). In general, this mount option is discouraged.
It's also possible to override permission checking on the client
altogether via the noperm
option. Server-side permission checks
cannot be overridden. The permission checks done by the server will
always correspond to the credentials used to mount the share, and not
necessarily to the user who is accessing the share.
The variable USER
may contain the username of the person to be used
to authenticate to the server. The variable can be used to set both
username and password by using the format username%password
.
The variable PASSWD
may contain the password of the person using
the client.
The variable PASSWD_FILE
may contain the pathname of a file to read
the password from. A single line of input is read and used as the
password.
This command may be used only by root, unless installed setuid, in which case the noexec and nosuid mount flags are enabled. When installed as a setuid program, the program follows the conventions set forth by the mount program for user mounts, with the added restriction that users must be able to chdir() into the mountpoint prior to the mount in order to be able to mount onto it.
Some samba client tools like smbclient(8) honour client-side
configuration parameters present in smb.conf. Unlike those client
tools, mount.cifs
ignores smb.conf completely.
The primary mechanism for making configuration changes and for reading
debug information for the cifs vfs is via the Linux /proc
filesystem. In the directory /proc/fs/cifs are various
configuration files and pseudo files which can display debug
information. There are additional startup options such as maximum
buffer size and number of buffers which only may be set when the
kernel cifs vfs (cifs.ko module) is loaded. These can be seen by
running the modinfo
utility against the file cifs.ko which will
list the options that may be passed to cifs during module installation
(device driver load). For more information see the kernel file
fs/cifs/README.
Mounting using the CIFS URL specification is currently not supported.
The credentials file does not handle usernames or passwords with leading space.
Note that the typical response to a bug report is a suggestion to try
the latest version first. So please try doing that first, and always
include which versions you use of relevant software when reporting
bugs (minimum: mount.cifs (try mount.cifs -V
), kernel (see
/proc/version) and server type you are trying to contact.
This man page is correct for version 1.74 of the cifs vfs filesystem (roughly Linux kernel 3.0).
cifs.upcall(8), getcifsacl(1), setcifsacl(1)
Documentation/filesystems/cifs.txt and fs/cifs/README in the Linux kernel source tree may contain additional options and information.
Steve French
The maintainer of the Linux cifs vfs and the userspace tool mount.cifs is Steve French. The Linux CIFS Mailing list is the preferred place to ask questions regarding these programs.