NAME¶

mount.cifs - mount using the Common Internet File System (CIFS)

SYNOPSIS¶

mount.cifs {service} {mount-point} [-o options]

DESCRIPTION¶

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.

OPTIONS¶

username=arg

password=arg

credentials=filename

		username=value
		password=value
		domain=value

uid=arg

forceuid

cruid=arg

gid=arg

forcegid

port=arg

servernetbiosname=arg

servern=arg

netbiosname=arg

file_mode=arg

dir_mode=arg

ip=arg

domain=arg

guest

iocharset

ro

rw

setuids

nosetuids

perm

noperm

dynperm

cache=

directio

strictcache

rwpidforward

mapchars

nomapchars

intr

nointr

hard

soft

noacl

cifsacl

backupuid=arg

backupgid=arg

nocase

ignorecase

sec=

nobrl

sfu

mfsymlinks

serverino

noserverino

nounix

nouser_xattr

rsize=bytes

wsize=bytes

fsc

multiuser

actimeo=arg

noposixpaths

posixpaths

prefixpath=

vers=

--verbose

SERVICE FORMATTING AND DELIMITERS¶

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 blackslashes (\) 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.

INODE NUMBERS¶

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.

CACHE COHERENCY¶

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".

CIFS/NTFS ACL, SID/UID/GID MAPPING, SECURITY DESCRIPTORS¶

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:

In order to map SIDs to/from UIDs and GIDs, the following is required:

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:

ACCESSING FILES WITH BACKUP INTENT¶

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 owenrship 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 group Backup Operators, 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 maching either backupuid or backupgid shall attempt to access files with backup intent. These two mount options can be used together.

FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS¶

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 overriden. 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.

ENVIRONMENT VARIABLES¶

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.

NOTES¶

This command may be used only by root, unless installed setuid, in which case the noeexec 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.

CONFIGURATION¶

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.

BUGS¶

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.

VERSION¶

This man page is correct for version 1.74 of the cifs vfs filesystem (roughly Linux kernel 3.0).

SEE ALSO¶

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.

AUTHOR¶

Steve French

The syntax and manpage were loosely based on that of smbmount. It was converted to Docbook/XML by Jelmer Vernooij.

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.