diff options
Diffstat (limited to 'mount.cifs.pod')
| -rw-r--r-- | mount.cifs.pod | 933 |
1 files changed, 0 insertions, 933 deletions
diff --git a/mount.cifs.pod b/mount.cifs.pod deleted file mode 100644 index 3a08dae..0000000 --- a/mount.cifs.pod +++ /dev/null @@ -1,933 +0,0 @@ -# turn into a manpage with the following command: -# -# pod2man -s 8 -c '' -r '' --stderr mount.cifs.pod mount.cifs.8 -# - -=head1 NAME - -mount.cifs - mount using the Common Internet File System (CIFS) - -=head1 SYNOPSIS - -mount.cifs {service} {mount-point} [-o options] - -This tool is part of the cifs-utils suite. - -B<mount.cifs> mounts a Linux CIFS filesystem. It is usually invoked -indirectly by the L<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 C<//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 B<umount> utility). - -C<mount.cifs -V> command displays the version of cifs mount helper. - -C<modinfo cifs> command displays the version of cifs module. - -=head1 OPTIONS - -=over - -=item B<username=arg> - -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 C<user%password> or C<workgroup/user> or -C<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 B<password=> and B<domain=> to specify those -values. While some versions of the cifs kernel module accept B<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 B<username=> option name. - -=item B<password=arg> - -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. - -=item B<credentials=filename> - -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 F</etc/fstab>. Be sure to protect any credentials file -properly. - -=item B<uid=arg> - -sets the uid that will own all files or directories on the mounted -filesystem when the server does not provide ownership information. It -may be specified as either a username or a numeric uid. When not -specified, the default is uid 0. The mount.cifs helper must be at -version 1.10 or higher to support specifying the uid in non-numeric -form. See the section on L</"FILE AND DIRECTORY OWNERSHIP AND -PERMISSIONS"> below for more information. - -=item B<forceuid> - -instructs the client to ignore any uid provided by the server for -files and directories and to always assign the owner to be the value -of the uid= option. See the section on L</"FILE AND DIRECTORY -OWNERSHIP AND PERMISSIONS"> below for more information. - -=item B<cruid=arg> - -sets the uid of the owner of the credentials cache. This is primarily -useful with 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. - -=item B<gid=arg> - -sets the gid that will own all files or directories on the mounted -filesystem when the server does not provide ownership information. It -may be specified as either a groupname or a numeric gid. When not -specified, the default is gid 0. The mount.cifs helper must be at -version 1.10 or higher to support specifying the gid in non-numeric -form. See the section on FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS -below for more information. - -=item B<forcegid> - -instructs the client to ignore any gid provided by the server for -files and directories and to always assign the owner to be the value -of the gid= option. See the section on FILE AND DIRECTORY OWNERSHIP -AND PERMISSIONS below for more information. - -=item B<port=arg> - -sets the port number on which the client will attempt to contact the -CIFS server. If this value is specified, look for an existing -connection with this port, and use that if one exists. If one doesn't -exist, try to create a new connection on that port. If that connection -fails, return an error. If this value isn't specified, look for an -existing connection on port 445 or 139. If no such connection exists, -try to connect on port 445 first and then port 139 if that -fails. Return an error if both fail. - -=item B<servernetbiosname=arg> - -Specify the server netbios name (RFC1001 name) to use when attempting -to setup a session to the server. Although rarely needed for mounting -to newer servers, this option is needed for mounting to some older -servers (such as OS/2 or Windows 98 and Windows ME) since when -connecting over port 139 they, unlike most newer servers, do not -support a default server name. A server name can be up to 15 -characters long and is usually uppercased. - -=item B<servern=arg> - -Synonym for B<servernetbiosname>. - -=item B<netbiosname=arg> - -When mounting to servers via port 139, specifies the RFC1001 source -name to use to represent the client netbios machine name when doing -the RFC1001 netbios session initialize. - -=item B<file_mode=arg> - -If the server does not support the CIFS Unix extensions this overrides -the default file mode. - -=item B<dir_mode=arg> - -If the server does not support the CIFS Unix extensions this overrides -the default mode for directories. - -=item B<ip=arg> - -sets the destination IP address. This option is set automatically if -the server name portion of the requested UNC name can be resolved so -rarely needs to be specified by the user. - -=item B<domain=arg> - -sets the domain (workgroup) of the user. - -=item B<guest> - -don't prompt for a password. - -=item B<iocharset> - -Charset used to convert local path names to and from Unicode. Unicode -is used by default for network path names if the server supports -it. If B<iocharset> is not specified then the B<nls_default> specified -during the local client kernel build will be used. If server does not -support Unicode, this parameter is unused. - -=item B<ro> - -mount read-only. - -=item B<rw> - -mount read-write. - -=item B<setuids> - -If the CIFS Unix extensions are negotiated with the server the client -will attempt to set the effective uid and gid of the local process on -newly created files, directories, and devices (create, mkdir, -mknod). If the CIFS Unix Extensions are not negotiated, for newly -created files and directories instead of using the default uid and gid -specified on the the mount, cache the new file's uid and gid locally -which means that the uid for the file can change when the inode is -reloaded (or the user remounts the share). - -=item B<nosetuids> - -The client will not attempt to set the uid and gid on on newly created -files, directories, and devices (create, mkdir, mknod) which will -result in the server setting the uid and gid to the default (usually -the server uid of the user who mounted the share). Letting the server -(rather than the client) set the uid and gid is the default. If the -CIFS Unix Extensions are not negotiated then the uid and gid for new -files will appear to be the uid (gid) of the mounter or the uid (gid) -parameter specified on the mount. - -=item B<perm> - -Client does permission checks (vfs_permission check of uid and gid of -the file against the mode and desired operation), Note that this is in -addition to the normal ACL check on the target machine done by the -server software. Client permission checking is enabled by default. - -=item B<noperm> - -Client does not do permission checks. This can expose files on this -mount to access by other users on the local client system. It is -typically only needed when the server supports the CIFS Unix -Extensions but the UIDs/GIDs on the client and server system do not -match closely enough to allow access by the user doing the mount. Note -that this does not affect the normal ACL check on the target machine -done by the server software (of the server ACL against the user name -provided at mount time). - -=item B<dynperm> - -Instructs the server to maintain ownership and permissions in memory -that can't be stored on the server. This information can disappear at -any time (whenever the inode is flushed from the cache), so while this -may help make some applications work, it's behavior is somewhat -unreliable. See the section below on FILE AND DIRECTORY OWNERSHIP AND -PERMISSIONS for more information. - -=item B<cache=arg> - -Cache mode. See the section below on L</"CACHE COHERENCY"> for -details. Allowed values are: - -=over - -=item * B<none> - do not cache file data at all - -=item * B<strict> - follow the CIFS/SMB2 protocol strictly - -=item * B<loose> - allow loose caching semantics - -=back - -The default in kernels prior to 3.7 was B<loose>. As of kernel 3.7 the -default is B<strict>. - -=item B<directio> - -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 -B<cache=none> instead on more recent kernels. - -=item B<strictcache> - -Use for switching on strict cache mode. In this mode the client reads -from the cache all the time it has I<Oplock Level II>, otherwise - -read from the server. As for write - the client stores a data in the -cache in I<Exclusive Oplock> case, otherwise - write directly to the -server. - -This option is will be deprecated in 3.7. Users should use -B<cache=strict> instead on more recent kernels. - -=item B<rwpidforward> - -Forward pid of a process who opened a file to any read or write -operation on that file. This prevent applications like L<wine(1)> from -failing on read and write if we use mandatory brlock style. - -=item B<mapchars> - -Translate six of the seven reserved characters (not backslash, but -including the colon, question mark, pipe, asterik, greater than and -less than characters) to the remap range (above 0xF000), which also -allows the CIFS client to recognize files created with such characters -by Windows's POSIX emulation. This can also be useful when mounting to -most versions of Samba (which also forbids creating and opening files -whose names contain any of these seven characters). This has no effect -if the server does not support Unicode on the wire. Please note that -the files created with B<mapchars> mount option may not be accessible -if the share is mounted without that option. - -=item B<nomapchars> - -Do not translate any of these seven characters (default). - -=item B<intr> - -currently unimplemented. - -=item B<nointr> - -(default) currently unimplemented. - -=item B<hard> - -The program accessing a file on the cifs mounted file system will hang -when the server crashes. - -=item B<soft> - -(default) The program accessing a file on the cifs mounted file system -will not hang when the server crashes and will return errors to the -user application. - -=item B<noacl> - -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 C<CIFS_XATTR> and then C<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 B<noacl> on mount. - -=item B<cifsacl> - -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 sections on L</"CIFS/NTFS ACL, SID/UID/GID MAPPING, SECURITY -DESCRIPTORS"> for more information. - -=item B<backupuid=arg> - -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 L</"ACCESSING FILES WITH BACKUP INTENT"> for more details. - -=item B<backupgid=arg> - -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 L</"ACCESSING FILES WITH BACKUP INTENT"> for more details. - -=item B<nocase> - -Request case insensitive path name matching (case sensitive is the default if the -server supports it). - -=item B<ignorecase> - -Synonym for B<nocase>. - -=item B<sec=arg> - -Security mode. Allowed values are: - -=over - -=item * B<none> - attempt to connection as a null user (no name) - -=item * B<krb5> - Use Kerberos version 5 authentication - -=item * B<krb5i> - Use Kerberos authentication and forcibly enable -packet signing - -=item * B<ntlm> - Use NTLM password hashing - -=item * B<ntlmi> - Use NTLM password hashing and force packet signing - -=item * B<ntlmv2> - Use NTLMv2 password hashing - -=item * B<ntlmv2i> - Use NTLMv2 password hashing and force packet -signing - -=item * B<ntlmssp> - Use NTLMv2 password hashing encapsulated in Raw -NTLMSSP message - -=item * B<ntlmsspi> - Use NTLMv2 password hashing encapsulated in Raw -NTLMSSP message, and force packet signing - -=back - -The default in mainline kernel versions prior to v3.8 was -B<sec=ntlm>. In v3.8, the default was changed to B<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 F</proc/fs/cifs/SecurityFlags>. - -=item B<seal> - -Request encryption at the SMB layer. Encryption is only supported in -SMBv3 and above. The encryption algorithm used is AES-128-CCM. - -=item B<nobrl> - -Do not send byte range lock requests to the server. This is necessary -for certain applications that break with cifs style mandatory byte -range locks (and most cifs servers do not yet support requesting -advisory byte range locks). - -=item B<sfu> - -When the CIFS Unix Extensions are not negotiated, attempt to create -device files and fifos in a format compatible with Services for Unix -(SFU). In addition retrieve bits 10-12 of the mode via the -C<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. - -=item B<mfsymlinks> - -Enable support for Minshall+French symlinks (see -L<http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks>). This -option is ignored when specified together with the B<sfu> -option. Minshall+French symlinks are used even if the server supports -the CIFS Unix Extensions. - -=item B<serverino> - -Use inode numbers (unique persistent file identifiers) returned by the -server instead of automatically generating temporary inode numbers on -the client. Although server inode numbers make it easier to spot -hardlinked files (as they will have the same inode numbers) and inode -numbers may be persistent (which is useful for some software), the -server does not guarantee that the inode numbers are unique if -multiple server side mounts are exported under a single share (since -inode numbers on the servers might not be unique if multiple -filesystems are mounted under the same shared higher level -directory). Note that not all servers support returning server inode -numbers, although those that support the CIFS Unix Extensions, and -Windows 2000 and later servers typically do support this (although not -necessarily on every local server filesystem). Parameter has no effect -if the server lacks support for returning inode numbers or -equivalent. This behavior is enabled by default. - -=item B<noserverino> - -Client generates inode numbers itself rather than using the actual -ones from the server. - -See section L</"INODE NUMBERS"> for more information. - -=item B<nounix> - -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 L</"INODE NUMBERS"> for more information. - -=item B<nouser_xattr> - -Do not allow getfattr/setfattr to get/set xattrs, even if server would -support it otherwise. The default is for xattr support to be enabled. - -=item B<rsize=bytes> - -Maximum amount of data that the kernel will request in a read request -in bytes. Prior to kernel 3.2.0, the default was 16k, and the maximum -size was limited by the C<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. - -=item B<wsize=bytes> - -Maximum amount of data that the kernel will send in a write request in -bytes. Prior to kernel 3.0.0, the default and maximum was 57344 (14 * -4096 pages). As of 3.0.0, the default depends on whether the client -and server negotiate large writes via POSIX extensions. If they do, -then the default is 1M, and the maximum allowed is 16M. If they do -not, then the default is 65536 and the maximum allowed is 131007. Note -that this value is just a starting point for negotiation in 3.0.0 and -up. The client and server may negotiate this size downward according -to the server's capabilities. In kernels prior to 3.0.0, no -negotiation is performed. It can end up with an existing superblock if -this value isn't specified or it's greater or equal than the existing -one. - -=item B<fsc> - -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. - -B<NOTE>: This feature is available only in the recent kernels that -have been built with the kernel config option -C<CONFIG_CIFS_FSCACHE>. You also need to have B<cachefilesd> daemon -installed and running to make the cache operational. - -=item B<multiuser> - -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 B<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 B<noperm>. Furthermore, when -unix extensions aren't in use and the administrator has not overridden -ownership using the B<uid=> or B<gid=> options, ownership of files is -presented as the current user accessing the share. - -=item B<actimeo=arg> - -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 B<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. - -=item B<noposixpaths> - -If unix extensions are enabled on a share, then the client will -typically allow filenames to include any character besides '/' in a -pathname component, and will use forward slashes as a pathname -delimiter. This option prevents the client from attempting to -negotiate the use of posix-style pathnames to the server. - -=item B<posixpaths> - -Inverse of B<noposixpaths>. - -=item B<prefixpath=arg> - -It's possible to mount a subdirectory of a share. The preferred way to -do this is to append the path to the UNC when mounting. However, it's -also possible to do the same by setting this option and providing the -path there. - -=item B<vers=arg> - -SMB protocol version. Allowed values are: - -=over - -=item * 1.0 - The classic CIFS/SMBv1 protocol. This is the default. - -=item * 2.0 - The SMBv2.002 protocol. This was initially introduced in -Windows Vista Service Pack 1, and Windows Server 2008. Note that the -initial release version of Windows Vista spoke a slightly different -dialect (2.000) that is not supported. - -=item * 2.1 - The SMBv2.1 protocol that was introduced in Microsoft -Windows 7 and Windows Server 2008R2. - -=item * 3.0 - The SMBv3.0 protocol that was introduced in Microsoft -Windows 8 and Windows Server 2012. - -=item * 3.1.1 or 3.11 - The SMBv3.1.1 protocol that was introduced in -Microsoft Windows Server 2016. - -Note too that while this option governs the protocol version used, not -all features of each version are available. - -=back - -=item B<--verbose> - -Print additional debugging information for the mount. Note that this -parameter must be specified before the B<-o>. For example: - - mount -t cifs //server/share /mnt --verbose -o user=username - -=back - -=head1 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 -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. - -B<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. - -=head1 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 B<serverino> mount option is -enabled there is no way to get the server inode number. The client -typically maps the server-assigned C<UniqueID> onto an inode number. - -Note that the C<UniqueID> is a different value from the server inode -number. The C<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 C<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 C<-D_FILE_OFFSET_BITS=64>) to prevent this -problem. You can also use B<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. - -=head1 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. - -B<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. - -B<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. - -B<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 C<LastWriteTime> field that -the client uses to verify this. The effect is that B<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 B<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 B<loose>. As of 3.7, the -default is B<strict>. - -=head1 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: - -L<http://technet.microsoft.com/en-us/library/bb463216.aspx> - -In order to map SIDs to/from UIDs and GIDs, the following is required: - -=over - -=item * a kernel upcall to the B<cifs.idmap> utility set up via -L<request-key.conf(5)> - -=item * winbind support configured via L<nsswitch.conf(5)> and -L<smb.conf(5)> - -=back - -Please refer to the respective manpages of L<cifs.idmap(8)> and -L<winbindd(8)> for more information. - -Security descriptors for a file object can be retrieved and set -directly using extended attribute named C<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 L<getcifsacl(1)> and L<setcifsacl(1)> -respectively. - -Some of the things to consider while using this mount option: - -=over - -=item * There may be an increased latency when handling metadata due -to additional requests to get and set security descriptors. - -=item * The mapping between a CIFS/NTFS ACL and POSIX file permission -bits is imperfect and some ACL information may be lost in the -translation. - -=item * If either upcall to cifs.idmap is not setup correctly or -winbind is not configured and running, ID mapping will fail. In that -case uid and gid will default to either to those values of the share -or to the values of uid and/or gid mount options if specified. - -=back - -=head1 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 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 I<Backup Operators>. Thus, when -this user attempts to open a file with the backup intent, open request -is sent by setting the bit C<FILE_OPEN_FOR_BACKUP_INTENT> as one of -the C<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 B<backupuid> is used to restrict this special right -to a user which is specified by either a name or an id. The mount -option B<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. - -=head1 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 B<uid=> or -B<gid=> options are set, and will have permissions set to the default -B<file_mode> and B<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 B<forceuid> and B<forcegid> options may be helpful. Note -however, that there is no corresponding option to override the -mode. Permissions assigned to a file when B<forceuid> or B<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 B<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 B<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. - -=head1 ENVIRONMENT VARIABLES - -The variable B<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 C<username%password>. - -The variable B<PASSWD> may contain the password of the person using -the client. - -The variable B<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. - -=head1 NOTES - -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 L<smbclient(8)> honour client-side -configuration parameters present in F<smb.conf>. Unlike those client -tools, B<mount.cifs> ignores F<smb.conf> completely. - -=head1 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 F</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 B<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 -F<fs/cifs/README>. - -=head1 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 C<mount.cifs -V>), kernel (see -F</proc/version>) and server type you are trying to contact. - -=head1 VERSION - -This man page is correct for version 1.74 of the cifs vfs filesystem -(roughly Linux kernel 3.0). - -=head1 SEE ALSO - -L<cifs.upcall(8)>, L<getcifsacl(1)>, L<setcifsacl(1)> - -F<Documentation/filesystems/cifs.txt> and F<fs/cifs/README> in the -linux kernel source tree may contain additional options and -information. - -=head1 AUTHOR - -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. |