1MOUNT.CIFS(8)                                                    MOUNT.CIFS(8)
2
3
4

NAME

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

SYNOPSIS

9          mount.cifs {service} {mount-point} [-o options]
10
11       This tool is part of the cifs-utils suite.
12
13       mount.cifs  mounts  a CIFS or SMB3 filesystem from Linux. It is usually
14       invoked indirectly by the mount(8) command when  using  the  "-t  cifs"
15       option.  This  command only works in Linux, and the kernel must support
16       the cifs filesystem. The SMB3 protocol is the  successor  to  the  CIFS
17       (SMB)  protocol  and is supported by most Windows servers, Azure (cloud
18       storage), Macs and many other commercial servers and  Network  Attached
19       Storage appliances as well as by the popular Open Source server Samba.
20
21       The   mount.cifs  utility  attaches  the  UNC  name  (exported  network
22       resource) specified as  service  (using  //server/share  syntax,  where
23       "server"  is  the  server name or IP address and "share" is the name of
24       the share) to the local directory mount-point.
25
26       Options to mount.cifs  are  specified  as  a  comma-separated  list  of
27       key=value pairs. It is possible to send options other than those listed
28       here, assuming that the cifs filesystem kernel  module  (cifs.ko)  sup‐
29       ports them. Unrecognized cifs mount options passed to the cifs vfs ker‐
30       nel code will be logged to the kernel log.
31
32       mount.cifs causes the cifs vfs to launch a thread  named  cifsd.  After
33       mounting it keeps running until the mounted resource is unmounted (usu‐
34       ally via the umount utility).
35
36       mount.cifs -V command displays the version of cifs mount helper.
37
38       modinfo cifs command displays the version of cifs module.
39

OPTIONS

41       username=arg|user=arg
42              specifies the username to connect as. If this is not given, then
43              the environment variable USER is used.
44
45              Earlier  versions  of mount.cifs also allowed one to specify the
46              username  in  a  user%password  or   workgroup/user   or   work‐
47              group/user%password  to  allow  the password and workgroup to be
48              specified as part of the username. Support for  those  alternate
49              username formats is now deprecated and should no longer be used.
50              Users should use the discrete password= and domain=  to  specify
51              those  values.  While  some  versions  of the cifs kernel module
52              accept user= as an abbreviation for this  option,  its  use  can
53              confuse  the standard mount program into thinking that this is a
54              non-superuser mount. It is therefore recommended to use the full
55              username= option name.
56
57       password=arg|pass=arg
58              specifies  the  CIFS  password. If this option is not given then
59              the environment variable PASSWD is used. If the password is  not
60              specified  directly  or  indirectly  via  an  argument to mount,
61              mount.cifs will prompt for a password, unless the  guest  option
62              is specified.
63
64              Note  that  a  password  which  contains the delimiter character
65              (i.e. a comma ',') will fail to be parsed correctly on the  com‐
66              mand  line.  However,  the  same  password defined in the PASSWD
67              environment variable or via a credentials file  (see  below)  or
68              entered at the password prompt will be read correctly.
69
70       credentials=filename|cred=filename
71              specifies  a  file  that contains a username and/or password and
72              optionally the name of the workgroup. The format of the file is:
73
74                 username=value
75                 password=value
76                 domain=value
77
78              This is preferred over having passwords in plaintext in a shared
79              file,  such  as  /etc/fstab . Be sure to protect any credentials
80              file properly.
81
82       uid=arg
83              sets the uid that will own  all  files  or  directories  on  the
84              mounted  filesystem  when  the server does not provide ownership
85              information. It may be specified  as  either  a  username  or  a
86              numeric  uid.  When  not  specified,  the  default is uid 0. The
87              mount.cifs helper must be at version 1.10 or higher  to  support
88              specifying  the uid in non-numeric form. See the section on FILE
89              AND DIRECTORY OWNERSHIP AND PERMISSIONS below for more  informa‐
90              tion.
91
92       forceuid
93              instructs  the  client  to ignore any uid provided by the server
94              for files and directories and to always assign the owner  to  be
95              the value of the uid= option. See the section on FILE AND DIREC‐
96              TORY OWNERSHIP AND PERMISSIONS below for more information.
97
98       cruid=arg
99              sets the uid of the owner of the credentials cache. This is pri‐
100              marily  useful with sec=krb5. The default is the real uid of the
101              process performing the mount. Setting this parameter directs the
102              upcall to look for a credentials cache owned by that user.
103
104       gid=arg
105              sets  the  gid  that  will  own  all files or directories on the
106              mounted filesystem when the server does  not  provide  ownership
107              information.  It  may  be  specified  as either a groupname or a
108              numeric gid. When not specified,  the  default  is  gid  0.  The
109              mount.cifs  helper  must be at version 1.10 or higher to support
110              specifying the gid in non-numeric form. See the section on  FILE
111              AND  DIRECTORY OWNERSHIP AND PERMISSIONS below for more informa‐
112              tion.
113
114       forcegid
115              instructs the client to ignore any gid provided  by  the  server
116              for  files  and directories and to always assign the owner to be
117              the value of the gid= option. See the section on FILE AND DIREC‐
118              TORY OWNERSHIP AND PERMISSIONS below for more information.
119
120       idsfromsid
121              Extract  uid/gid from special SID instead of mapping it. See the
122              section on FILE AND DIRECTORY OWNERSHIP  AND  PERMISSIONS  below
123              for more information.
124
125       port=arg
126              sets the port number on which the client will attempt to contact
127              the CIFS server. If this value is specified, look for an  exist‐
128              ing  connection  with  this port, and use that if one exists. If
129              one doesn't exist, try to create a new connection on that  port.
130              If  that  connection fails, return an error. If this value isn't
131              specified, look for an existing connection on port 445  or  139.
132              If  no  such connection exists, try to connect on port 445 first
133              and then port 139 if that fails. Return an error if both fail.
134
135       netbiosname=arg
136              When mounting to servers via port  139,  specifies  the  RFC1001
137              source  name to use to represent the client netbios machine dur‐
138              ing the netbios session initialization.
139
140       servern=arg
141              Similar to netbiosname except it specifies the netbios  name  of
142              the  server  instead  of  the client. Although rarely needed for
143              mounting to newer servers, this option is needed for mounting to
144              some  older  servers (such as OS/2 or Windows 98 and Windows ME)
145              since when connecting over port  139  they,  unlike  most  newer
146              servers, do not support a default server name. A server name can
147              be up to 15 characters long and is usually uppercased.
148
149       file_mode=arg
150              If the server does not support the  CIFS  Unix  extensions  this
151              overrides the default file mode.
152
153       dir_mode=arg
154              If  the  server  does  not support the CIFS Unix extensions this
155              overrides the default mode for directories.
156
157       ip=arg|addr=arg
158              sets the destination IP address. This option  is  set  automati‐
159              cally  if  the server name portion of the requested UNC name can
160              be resolved so rarely needs to be specified by the user.
161
162       domain=arg|dom=arg|workgroup=arg
163              Sets the domain (workgroup) of  the  user.  If  no  domains  are
164              given, the empty domain will be used. Use domainauto to automat‐
165              ically guess the domain of the server you are connecting to.
166
167       domainauto
168              When using NTLM authentication and not providing  a  domain  via
169              domain,  guess  the domain from the server NTLM challenge.  This
170              behavior used to be the default on kernels older than 2.6.36.
171
172       guest  don't prompt for a password.
173
174       iocharset
175              Charset used to convert local path names to  and  from  Unicode.
176              Unicode  is used by default for network path names if the server
177              supports it. If iocharset is not specified then the  nls_default
178              specified  during the local client kernel build will be used. If
179              server does not support Unicode, this parameter is unused.
180
181       ro     mount read-only.
182
183       rw     mount read-write.
184
185       setuids
186              If the CIFS Unix extensions are negotiated with the  server  the
187              client  will  attempt  to  set  the effective uid and gid of the
188              local process on newly created files, directories,  and  devices
189              (create,  mkdir,  mknod).  If  the  CIFS Unix Extensions are not
190              negotiated, for newly created files and directories  instead  of
191              using  the default uid and gid specified on the the mount, cache
192              the new file's uid and gid locally which means that the uid  for
193              the  file  can  change  when  the inode is reloaded (or the user
194              remounts the share).
195
196       nosetuids
197              The client will not attempt to set the uid and gid on  on  newly
198              created  files,  directories, and devices (create, mkdir, mknod)
199              which will result in the server setting the uid and gid  to  the
200              default  (usually  the  server  uid  of the user who mounted the
201              share). Letting the server (rather than the client) set the  uid
202              and  gid  is  the  default.  If the CIFS Unix Extensions are not
203              negotiated then the uid and gid for new files will appear to  be
204              the  uid  (gid) of the mounter or the uid (gid) parameter speci‐
205              fied on the mount.
206
207       perm   Client does permission checks (vfs_permission check of  uid  and
208              gid  of  the  file against the mode and desired operation), Note
209              that this is in addition to the normal ACL check on  the  target
210              machine  done by the server software. Client permission checking
211              is enabled by default.
212
213       noperm Client does not do permission checks. This can expose  files  on
214              this  mount to access by other users on the local client system.
215              It is typically only needed when the server  supports  the  CIFS
216              Unix  Extensions but the UIDs/GIDs on the client and server sys‐
217              tem do not match closely enough to  allow  access  by  the  user
218              doing  the  mount. Note that this does not affect the normal ACL
219              check on the target machine done by the server software (of  the
220              server ACL against the user name provided at mount time).
221
222       dynperm
223              Instructs  the  server  to maintain ownership and permissions in
224              memory that can't be stored on the server. This information  can
225              disappear  at  any  time (whenever the inode is flushed from the
226              cache), so while this may help make some applications work, it's
227              behavior  is  somewhat unreliable. See the section below on FILE
228              AND DIRECTORY OWNERSHIP AND PERMISSIONS for more information.
229
230       cache=arg
231              Cache mode.  See  the  section  below  on  CACHE  COHERENCY  for
232              details. Allowed values are:
233
234              · none - do not cache file data at all
235
236              · strict - follow the CIFS/SMB2 protocol strictly
237
238              · loose - allow loose caching semantics
239
240              The  default in kernels prior to 3.7 was loose. As of kernel 3.7
241              the default is strict.
242
243       nostrictsync
244              Do not ask the server to flush on fsync().  Some servers perform
245              non-buffered  writes by default in which case flushing is redun‐
246              dant. In workloads where a client is performing a lot  of  small
247              write  +  fsync  combinations  and where network latency is much
248              higher than the server latency, this  brings  a  2x  performance
249              improvement.   This option is also a good candidate in scenarios
250              where we want performance over consistency.
251
252       handlecache
253              (default) In SMB2 and above, the client often has  to  open  the
254              root  of  the share (empty path) in various places during mount,
255              path revalidation and the statfs(2)  system  call.  This  option
256              cuts  redundant  round trip traffic (opens and closes) by simply
257              keeping the directory handle for the root around once opened.
258
259       nohandlecache
260              Disable caching of the share root directory handle.
261
262       handletimeout=arg
263              The time (in milliseconds) for which the server  should  reserve
264              the handle after a failover waiting for the client to reconnect.
265              When mounting with resilienthandles or  persistenthandles  mount
266              option, or when their use is requested by the server (continuous
267              availability shares) then this parameter  overrides  the  server
268              default handle timeout (which for most servers is 120 seconds).
269
270       rwpidforward
271              Forward  pid of a process who opened a file to any read or write
272              operation on that file. This prevent applications  like  wine(1)
273              from failing on read and write if we use mandatory brlock style.
274
275       mapchars
276              Translate  six  of the seven reserved characters (not backslash,
277              but including the colon, question mark, pipe,  asterik,  greater
278              than  and  less  than  characters)  to  the  remap  range (above
279              0xF000), which also allows the CIFS client  to  recognize  files
280              created with such characters by Windows's Services for Mac. This
281              can also be useful when  mounting  to  most  versions  of  Samba
282              (which  also forbids creating and opening files whose names con‐
283              tain any of these seven characters). This has no effect  if  the
284              server  does  not  support Unicode on the wire. Please note that
285              the files created with mapchars mount option may not be accessi‐
286              ble if the share is mounted without that option.
287
288       nomapchars
289              (default) Do not translate any of these seven characters.
290
291       mapposix
292              Translate  reserved characters similarly to mapchars but use the
293              mapping from Microsoft "Services For Unix".
294
295       intr   currently unimplemented.
296
297       nointr (default) currently unimplemented.
298
299       hard   The program accessing a file on the  cifs  mounted  file  system
300              will hang when the server crashes.
301
302       soft   (default)  The program accessing a file on the cifs mounted file
303              system will not hang when the server  crashes  and  will  return
304              errors to the user application.
305
306       noacl  Do  not  allow POSIX ACL operations even if server would support
307              them.
308
309              The CIFS client can get and set POSIX ACLs (getfacl, setfacl) to
310              Samba  servers  version  3.0.10  and  later.  Setting POSIX ACLs
311              requires enabling both CIFS_XATTR and then CIFS_POSIX support in
312              the  CIFS  configuration  options when building the cifs module.
313              POSIX ACL support can be disabled on a per mount basis by speci‐
314              fying noacl on mount.
315
316       cifsacl
317              This  option is used to map CIFS/NTFS ACLs to/from Linux permis‐
318              sion bits, map SIDs to/from UIDs and GIDs, and get and set Secu‐
319              rity Descriptors.
320
321              See  section  on  CIFS/NTFS  ACL,  SID/UID/GID MAPPING, SECURITY
322              DESCRIPTORS for more information.
323
324       backupuid=arg
325              File access by this user shall be done with  the  backup  intent
326              flag  set.  Either  a name or an id must be provided as an argu‐
327              ment, there are no default values.
328
329              See section ACCESSING FILES WITH BACKUP INTENT for more details.
330
331       backupgid=arg
332              File access by users who are members of this group shall be done
333              with  the backup intent flag set. Either a name or an id must be
334              provided as an argument, there are no default values.
335
336              See section ACCESSING FILES WITH BACKUP INTENT for more details.
337
338       nocase Request case insensitive path name matching (case  sensitive  is
339              the default if the server supports it).
340
341       ignorecase
342              Synonym for nocase.
343
344       sec=arg
345              Security mode. Allowed values are:
346
347              · none - attempt to connection as a null user (no name)
348
349              · krb5 - Use Kerberos version 5 authentication
350
351              · krb5i - Use Kerberos authentication and forcibly enable packet
352                signing
353
354              · ntlm - Use NTLM password hashing
355
356              · ntlmi - Use NTLM password hashing and force packet signing
357
358              · ntlmv2 - Use NTLMv2 password hashing
359
360              · ntlmv2i - Use NTLMv2 password hashing and force packet signing
361
362              · ntlmssp - Use NTLMv2  password  hashing  encapsulated  in  Raw
363                NTLMSSP message
364
365              · ntlmsspi  -  Use  NTLMv2  password hashing encapsulated in Raw
366                NTLMSSP message, and force packet signing
367
368              The default in  mainline  kernel  versions  prior  to  v3.8  was
369              sec=ntlm. In v3.8, the default was changed to sec=ntlmssp.
370
371              If the server requires signing during protocol negotiation, then
372              it may be enabled automatically.  Packet  signing  may  also  be
373              enabled  automatically  if it's enabled in /proc/fs/cifs/Securi‐
374              tyFlags.
375
376       seal   Request encryption at the SMB layer.  The  encryption  algorithm
377              used is AES-128-CCM. Requires SMB3 or above (see vers).
378
379       rdma   Connect  directly  to  the  server  using  SMB Direct via a RDMA
380              adapter. Requires SMB3 or above (see vers).
381
382       resilienthandles
383              Enable resilient handles. If the server supports it, keep opened
384              files across reconnections. Requires SMB2.1 (see vers).
385
386       noresilienthandles
387              (default) Disable resilient handles.
388
389       persistenthandles
390              Enable  persistent  handles.  If  the  server  supports it, keep
391              opened files across reconnections. Persistent handles  are  also
392              valid  across  servers in a cluster and have stronger guarantees
393              than resilient handles. Requires SMB3 or above (see vers).
394
395       nopersistenthandles
396              (default) Disable persistent handles.
397
398       snapshot=time
399              Mount a specific snapshot of the remote share. time  must  be  a
400              positive   integer   identifying   the  snapshot  requested  (in
401              100-nanosecond units that have elapsed since January 1, 1601, or
402              alternatively   it   can   be   specified  in  GMT  format  e.g.
403              @GMT-2019.03.27-20.52.19). Supported in the Linux kernel  start‐
404              ing from v4.19.
405
406       nobrl  Do not send byte range lock requests to the server. This is nec‐
407              essary for certain  applications  that  break  with  cifs  style
408              mandatory  byte  range  locks  (and most cifs servers do not yet
409              support requesting advisory byte range locks).
410
411       forcemandatorylock
412              Do not use POSIX locks even when available via unix  extensions.
413              Always use cifs style mandatory locks.
414
415       locallease
416              Check cached leases locally instead of querying the server.
417
418       sfu    When  the  CIFS  or  SMB3  Unix  Extensions  are not negotiated,
419              attempt to create device files and fifos in a format  compatible
420              with Services for Unix (SFU). In addition retrieve bits 10-12 of
421              the mode via the SETFILEBITS extended attribute (as  SFU  does).
422              In  the  future  the bottom 9 bits of the mode mode also will be
423              emulated using queries of the security  descriptor  (ACL).  [NB:
424              requires  version  1.39  or  later of the CIFS VFS. To recognize
425              symlinks and be able to create symlinks in an SFU  interoperable
426              form  requires version 1.40 or later of the CIFS VFS kernel mod‐
427              ule.
428
429       mfsymlinks
430              Enable    support    for    Minshall+French    symlinks     (see
431              http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks).
432              This option is ignored when  specified  together  with  the  sfu
433              option.  Minshall+French  symlinks  are  used even if the server
434              supports the CIFS Unix Extensions.
435
436       echo_interval=n
437              sets the interval at which echo requests are sent to the  server
438              on  an  idling  connection.  This  setting also affects the time
439              required for a connection to an unresponsive server to  timeout.
440              Here n is the echo interval in seconds. The reconnection happens
441              at twice the value of the echo_interval set for an  unresponsive
442              server.   If  this option is not given then the default value of
443              60 seconds is used.  The minimum tunable value is 1  second  and
444              maximum can go up to 600 seconds.
445
446       serverino
447              Use  inode numbers (unique persistent file identifiers) returned
448              by the server  instead  of  automatically  generating  temporary
449              inode  numbers on the client. Although server inode numbers make
450              it easier to spot hardlinked files (as they will have  the  same
451              inode  numbers)  and  inode  numbers may be persistent (which is
452              useful for some software), the server does  not  guarantee  that
453              the  inode numbers are unique if multiple server side mounts are
454              exported under a  single  share  (since  inode  numbers  on  the
455              servers  might not be unique if multiple filesystems are mounted
456              under the same shared higher level directory). Note that not all
457              servers  support  returning server inode numbers, although those
458              that support the CIFS Unix  Extensions,  and  Windows  2000  and
459              later  servers typically do support this (although not necessar‐
460              ily on every local server filesystem). Parameter has  no  effect
461              if  the  server  lacks  support  for  returning inode numbers or
462              equivalent. This behavior is enabled by default.
463
464       noserverino
465              Client generates inode numbers  itself  rather  than  using  the
466              actual ones from the server.
467
468              See section INODE NUMBERS for more information.
469
470       posix|unix|linux
471              (default)  Enable  Unix Extensions for this mount. Requires CIFS
472              (vers=1.0) or SMB3.1.1  (vers=3.1.1)  and  a  server  supporting
473              them.
474
475       noposix|nounix|nolinux
476              Disable  the  Unix Extensions for this mount. This can be useful
477              in order to turn off multiple settings at  once.  This  includes
478              POSIX  acls,  POSIX  locks,  POSIX  paths,  symlink  support and
479              retrieving uids/gids/mode from the server. This can also be use‐
480              ful  to  work around a bug in a server that supports Unix Exten‐
481              sions.
482
483              See section INODE NUMBERS for more information.
484
485       nouser_xattr
486              Do not allow getfattr/setfattr to get/set xattrs, even if server
487              would  support it otherwise. The default is for xattr support to
488              be enabled.
489
490       nodfs  Do not follow Distributed FileSystem referrals. IO on a file not
491              stored on the server will fail instead of connecting to the tar‐
492              get server transparently.
493
494       noautotune
495              Use fixed size for kernel recv/send socket buffers.
496
497       nosharesock
498              Do not try to reuse sockets if the system is  already  connected
499              to  the  server  via an existing mount point. This will make the
500              client always make a new connection to the server no matter what
501              he  is  already  connected  to. This can be useful in simulating
502              multiple clients connecting to the same server,  as  each  mount
503              point will use a different TCP socket.
504
505       noblocksend
506              Send data on the socket using non blocking operations (MSG_DONT‐
507              WAIT flag).
508
509       rsize=bytes
510              Maximum amount of data that the kernel will request  in  a  read
511              request in bytes. Maximum size that servers will accept is typi‐
512              cally 8MB for SMB3 or later dialects. Default  requested  during
513              mount is 4MB. Prior to the 4.20 kernel the default requested was
514              1MB. Prior to the SMB2.1 dialect the maximum was usually 64K.
515
516       wsize=bytes
517              Maximum amount of data that the kernel  will  send  in  a  write
518              request in bytes. Maximum size that servers will accept is typi‐
519              cally 8MB for SMB3 or later dialects. Default  requested  during
520              mount is 4MB. Prior to the 4.20 kernel the default requested was
521              1MB. Prior to the SMB2.1 dialect the maximum was usually 64K.
522
523       bsize=bytes
524              Override the default blocksize  (1MB)  reported  on  SMB3  files
525              (requires  kernel version of 5.1 or later). Prior to kernel ver‐
526              sion 5.1, the blocksize was always reported as  16K  instead  of
527              1MB (and was not configurable) which can hurt the performance of
528              tools like cp and scp (especially for uncached I/O) which decide
529              on  the  read and write size to use for file copies based on the
530              inode blocksize. bsize may not be less than 16K or greater  than
531              16M.
532
533       max_credits=n
534              Maximum credits the SMB2 client can have. Default is 32000. Must
535              be set to a number between 20 and 60000.
536
537       fsc    Enable local disk caching using FS-Cache for CIFS.  This  option
538              could  be  useful to improve performance on a slow link, heavily
539              loaded server and/or network where  reading  from  the  disk  is
540              faster  than  reading  from  the server (over the network). This
541              could also impact the scalability positively as  the  number  of
542              calls  to  the  server  are  reduced.  But, be warned that local
543              caching is not suitable for all workloads, for  e.g.,  read-once
544              type  workloads.  So,  you need to consider carefully the situa‐
545              tion/workload before using this option.  Currently,  local  disk
546              caching is enabled for CIFS files opened as read-only.
547
548              NOTE:  This feature is available only in the recent kernels that
549              have  been  built   with   the   kernel   config   option   CON‐
550              FIG_CIFS_FSCACHE.  You  also  need  to  have  cachefilesd daemon
551              installed and running to make the cache operational.
552
553       multiuser
554              Map user accesses to individual credentials when  accessing  the
555              server.  By  default,  CIFS mounts only use a single set of user
556              credentials (the mount credentials) when accessing a share. With
557              this  option,  the client instead creates a new session with the
558              server using the user's credentials whenever a new user accesses
559              the  mount.   Further  accesses by that user will also use those
560              credentials. Because the kernel  cannot  prompt  for  passwords,
561              multiuser  mounts  are limited to mounts using sec= options that
562              don't require passwords.
563
564              With this change, it's feasible for the server to handle permis‐
565              sions enforcement, so this option also implies noperm . Further‐
566              more, when unix extensions aren't in use and  the  administrator
567              has  not  overridden  ownership  using the uid= or gid= options,
568              ownership of files is presented as the  current  user  accessing
569              the share.
570
571       actimeo=arg
572              The  time (in seconds) that the CIFS client caches attributes of
573              a file or directory before  it  requests  attribute  information
574              from  a server. During this period the changes that occur on the
575              server remain undetected until  the  client  checks  the  server
576              again.
577
578              By default, the attribute cache timeout is set to 1 second. This
579              means more frequent on-the-wire calls to  the  server  to  check
580              whether  attributes have changed which could impact performance.
581              With this option users can make a tradeoff  between  performance
582              and  cache  metadata  correctness,  depending on workload needs.
583              Shorter timeouts  mean  better  cache  coherency,  but  frequent
584              increased  number of calls to the server. Longer timeouts mean a
585              reduced  number  of  calls  to  the  server  but  looser   cache
586              coherency. The actimeo value is a positive integer that can hold
587              values between 0 and a maximum value of 2^30 * HZ (frequency  of
588              timer interrupt) setting.
589
590       noposixpaths
591              If  unix extensions are enabled on a share, then the client will
592              typically allow filenames to include any character  besides  '/'
593              in a pathname component, and will use forward slashes as a path‐
594              name delimiter. This option prevents the client from  attempting
595              to negotiate the use of posix-style pathnames to the server.
596
597       posixpaths
598              Inverse of noposixpaths .
599
600       prefixpath=arg
601              It's  possible to mount a subdirectory of a share. The preferred
602              way to do this is to append the path to the UNC  when  mounting.
603              However,  it's  also  possible  to  do  the same by setting this
604              option and providing the path there.
605
606       vers=arg
607              SMB protocol version. Allowed values are:
608
609              · 1.0 - The classic CIFS/SMBv1 protocol.
610
611              · 2.0 - The SMBv2.002 protocol. This was initially introduced in
612                Windows  Vista  Service  Pack 1, and Windows Server 2008. Note
613                that the initial release version  of  Windows  Vista  spoke  a
614                slightly different dialect (2.000) that is not supported.
615
616              · 2.1  -  The  SMBv2.1 protocol that was introduced in Microsoft
617                Windows 7 and Windows Server 2008R2.
618
619              · 3.0 - The SMBv3.0 protocol that was  introduced  in  Microsoft
620                Windows 8 and Windows Server 2012.
621
622              · 3.02  or 3.0.2 - The SMBv3.0.2 protocol that was introduced in
623                Microsoft Windows 8.1 and Windows Server 2012R2.
624
625              · 3.1.1 or 3.11 - The SMBv3.1.1 protocol that was introduced  in
626                Microsoft Windows 10 and Windows Server 2016.
627
628              · 3 - The SMBv3.0 protocol version and above.
629
630              · default  -  Tries  to negotiate the highest SMB2+ version sup‐
631                ported by both the client and server.
632
633              If no dialect is specified on mount vers=default  is  used.   To
634              check Dialect refer to /proc/fs/cifs/DebugData
635
636              Note  too  that  while  this option governs the protocol version
637              used, not all features of each version are available.
638
639              The default since v4.13.5 is for the client and server to  nego‐
640              tiate the highest possible version greater than or equal to 2.1.
641              In kernels prior to v4.13, the  default  was  1.0.  For  kernels
642              between v4.13 and v4.13.5 the default is 3.0.
643
644       --verbose
645              Print  additional debugging information for the mount. Note that
646              this parameter must be specified before the -o . For example:
647
648                 mount -t cifs //server/share /mnt --verbose -o user=username
649

SERVICE FORMATTING AND DELIMITERS

651       It's generally preferred to use forward slashes (/) as a  delimiter  in
652       service  names.  They  are  considered  to be the "universal delimiter"
653       since they are generally not allowed to be embedded within path  compo‐
654       nents  on  Windows  machines  and  the client can convert them to back‐
655       slashes  (\)  unconditionally.  Conversely,  backslash  characters  are
656       allowed by POSIX to be part of a path component, and can't be automati‐
657       cally converted in the same way.
658
659       mount.cifs will attempt to convert backslashes to forward slashes where
660       it's able to do so, but it cannot do so in any path component following
661       the sharename.
662

INODE NUMBERS

664       When Unix Extensions are enabled, we use the actual inode  number  pro‐
665       vided by the server in response to the POSIX calls as an inode number.
666
667       When Unix Extensions are disabled and serverino mount option is enabled
668       there is no way to get the server inode number.  The  client  typically
669       maps the server-assigned UniqueID onto an inode number.
670
671       Note  that the UniqueID is a different value from the server inode num‐
672       ber. The UniqueID value is unique over the scope of the  entire  server
673       and  is  often greater than 2 power 32. This value often makes programs
674       that are not compiled with LFS (Large File Support), to trigger a glibc
675       EOVERFLOW  error as this won't fit in the target structure field. It is
676       strongly recommended to compile your programs with  LFS  support  (i.e.
677       with  -D_FILE_OFFSET_BITS=64) to prevent this problem. You can also use
678       noserverino mount option to generate inode numbers smaller than 2 power
679       32 on the client. But you may not be able to detect hardlinks properly.
680

CACHE COHERENCY

682       With  a network filesystem such as CIFS or NFS, the client must contend
683       with the fact that activity on other clients or the server could change
684       the  contents or attributes of a file without the client being aware of
685       it. One way to deal with such a problem is to  mandate  that  all  file
686       accesses  go  to  the  server directly. This is performance prohibitive
687       however, so most protocols have some mechanism to allow the  client  to
688       cache data locally.
689
690       The CIFS protocol mandates (in effect) that the client should not cache
691       file data unless it holds an  opportunistic  lock  (aka  oplock)  or  a
692       lease.  Both  of  these  entities allow the client to guarantee certain
693       types of exclusive access to a file so that it can access its  contents
694       without  needing  to  continually  interact with the server. The server
695       will call back the client when it needs to revoke either  of  them  and
696       allow the client a certain amount of time to flush any cached data.
697
698       The cifs client uses the kernel's pagecache to cache file data. Any I/O
699       that's done through the pagecache is generally page-aligned.  This  can
700       be  problematic when combined with byte-range locks as Windows' locking
701       is mandatory and can block reads and writes from occurring.
702
703       cache=none means that the client never utilizes the  cache  for  normal
704       reads  and  writes. It always accesses the server directly to satisfy a
705       read or write request.
706
707       cache=strict means that the client will attempt to follow the CIFS/SMB2
708       protocol  strictly.  That is, the cache is only trusted when the client
709       holds an oplock. When the client does not  hold  an  oplock,  then  the
710       client bypasses the cache and accesses the server directly to satisfy a
711       read or write request. By doing this, the client avoids  problems  with
712       byte  range  locks.  Additionally,  byte  range locks are cached on the
713       client when it holds an oplock and are "pushed" to the server when that
714       oplock is recalled.
715
716       cache=loose  allows  the  client to use looser protocol semantics which
717       can sometimes provide  better  performance  at  the  expense  of  cache
718       coherency. File access always involves the pagecache. When an oplock or
719       lease is not held, then the client will attempt to flush the cache soon
720       after  a  write  to  a  file. Note that that flush does not necessarily
721       occur before a write system call returns.
722
723       In the case of a read  without  holding  an  oplock,  the  client  will
724       attempt  to  periodically  check the attributes of the file in order to
725       ascertain whether it has changed and  the  cache  might  no  longer  be
726       valid.  This  mechanism is much like the one that NFSv2/3 use for cache
727       coherency, but it particularly problematic with CIFS. Windows is  quite
728       "lazy" with respect to updating the LastWriteTime field that the client
729       uses to verify this. The effect is that cache=loose can cause data cor‐
730       ruption  when  multiple  readers  and  writers  are working on the same
731       files.
732
733       Because of this, when multiple clients are accessing the  same  set  of
734       files,  then cache=strict is recommended. That helps eliminate problems
735       with  cache  coherency  by  following  the  CIFS/SMB2  protocols   more
736       strictly.
737
738       Note  too  that  no  matter what caching model is used, the client will
739       always use the pagecache to handle mmap'ed  files.  Writes  to  mmap'ed
740       files  are  only guaranteed to be flushed to the server when msync() is
741       called, or on close().
742
743       The default in kernels prior to 3.7 was loose. As of 3.7,  the  default
744       is strict.
745

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

747       This  option  is  used  to work with file objects which posses Security
748       Descriptors and CIFS/NTFS ACL instead  of  UID,  GID,  file  permission
749       bits, and POSIX ACL as user authentication model. This is the most com‐
750       mon authentication model for CIFS servers and is the one used  by  Win‐
751       dows.
752
753       Support  for  this requires both CIFS_XATTR and CIFS_ACL support in the
754       CIFS configuration options when building the cifs module.
755
756       A CIFS/NTFS ACL is mapped to file permission bits  using  an  algorithm
757       specified in the following Microsoft TechNet document:
758
759       http://technet.microsoft.com/en-us/library/bb463216.aspx
760
761       In order to map SIDs to/from UIDs and GIDs, the following is required:
762
763       · a   kernel   upcall   to   the   cifs.idmap   utility   set   up  via
764         request-key.conf(5)
765
766       · winbind support configured via nsswitch.conf(5) and smb.conf(5)
767
768       Please refer to the  respective  manpages  of  cifs.idmap(8)  and  win‐
769       bindd(8) for more information.
770
771       Security  descriptors  for  a  file  object  can  be  retrieved and set
772       directly using extended attribute named system.cifs_acl.  The  security
773       descriptors  presented  via  this interface are "raw" blobs of data and
774       need a userspace utility to either parse and format or to  assemble  it
775       such as getcifsacl(1) and setcifsacl(1) respectively.
776
777       Some of the things to consider while using this mount option:
778
779       · There may be an increased latency when handling metadata due to addi‐
780         tional requests to get and set security descriptors.
781
782       · The mapping between a CIFS/NTFS ACL and POSIX file permission bits is
783         imperfect and some ACL information may be lost in the translation.
784
785       · If  either  upcall to cifs.idmap is not setup correctly or winbind is
786         not configured and running, ID mapping will fail. In  that  case  uid
787         and gid will default to either to those values of the share or to the
788         values of uid and/or gid mount options if specified.
789

ACCESSING FILES WITH BACKUP INTENT

791       For an user on the server, desired access to a file  is  determined  by
792       the permissions and rights associated with that file. This is typically
793       accomplished using ownership and ACL. For a  user  who  does  not  have
794       access rights to a file, it is still possible to access that file for a
795       specific or a targeted purpose by granting special rights.  One of  the
796       specific  purposes is to access a file with the intent to either backup
797       or restore i.e. backup intent. The right to  access  a  file  with  the
798       backup  intent  can  typically be granted by making that user a part of
799       the built-in group Backup Operators. Thus, when this user  attempts  to
800       open a file with the backup intent, open request is sent by setting the
801       bit FILE_OPEN_FOR_BACKUP_INTENT as one of the CreateOptions.
802
803       As an example, on a Windows server, a user named testuser, cannot  open
804       this file with such a security descriptor:
805
806          REVISION:0x1
807          CONTROL:0x9404
808          OWNER:Administrator
809          GROUP:Domain Users
810          ACL:Administrator:ALLOWED/0x0/FULL
811
812       But  the  user  testuser,  if  it  becomes part of the Backup Operators
813       group, can open the file with the backup intent.
814
815       Any user on the client side who can authenticate as such a user on  the
816       server,  can  access the files with the backup intent. But it is desir‐
817       able and preferable for security reasons amongst many, to restrict this
818       special right.
819
820       The  mount option backupuid is used to restrict this special right to a
821       user which is specified by either a name or an  id.  The  mount  option
822       backupgid  is  used  to  restrict  this special right to the users in a
823       group which is specified by either a name or an id. Only users matching
824       either backupuid or backupgid shall attempt to access files with backup
825       intent. These two mount options can be used together.
826

FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS

828       The core CIFS protocol does not provide unix ownership  information  or
829       mode  for files and directories. Because of this, files and directories
830       will generally appear to be owned by whatever values the uid=  or  gid=
831       options are set, and will have permissions set to the default file_mode
832       and dir_mode for the mount.  Attempting  to  change  these  values  via
833       chmod/chown will return success but have no effect.
834
835       When  the client and server negotiate unix extensions, files and direc‐
836       tories will be assigned the uid, gid, and mode provided by the  server.
837       Because CIFS mounts are generally single-user, and the same credentials
838       are used no matter what user accesses the mount,  newly  created  files
839       and  directories  will  generally  be  given ownership corresponding to
840       whatever credentials were used to mount the share.
841
842       If the uid's and gid's being used  do  not  match  on  the  client  and
843       server, the forceuid and forcegid options may be helpful. Note however,
844       that there is no corresponding option to override the mode. Permissions
845       assigned  to  a  file  when  forceuid or forcegid are in effect may not
846       reflect the the real permissions.
847
848       When unix extensions are not negotiated, it's also possible to  emulate
849       them  locally  on  the server using the dynperm mount option. When this
850       mount option is in effect, newly created  files  and  directories  will
851       receive what appear to be proper permissions. These permissions are not
852       stored on the server however and can  disappear  at  any  time  in  the
853       future  (subject  to  the  whims  of  the kernel flushing out the inode
854       cache). In general, this mount option is discouraged.
855
856       It's also possible to override permission checking on the client  alto‐
857       gether  via  the noperm option. Server-side permission checks cannot be
858       overridden. The permission checks done by the server will always corre‐
859       spond  to  the credentials used to mount the share, and not necessarily
860       to the user who is accessing the share.
861

ENVIRONMENT VARIABLES

863       The variable USER may contain the username of the person to be used  to
864       authenticate  to the server. The variable can be used to set both user‐
865       name and password by using the format username%password.
866
867       The variable PASSWD may contain the password of the  person  using  the
868       client.
869
870       The variable PASSWD_FILE may contain the pathname of a file to read the
871       password from. A single line of input is read and used as the password.
872

NOTES

874       This command may be used only by  root,  unless  installed  setuid,  in
875       which  case  the  noexec  and  nosuid  mount  flags  are  enabled. When
876       installed as a setuid program, the program follows the conventions  set
877       forth  by the mount program for user mounts, with the added restriction
878       that users must be able to chdir() into the  mountpoint  prior  to  the
879       mount in order to be able to mount onto it.
880
881       Some samba client tools like smbclient(8) honour client-side configura‐
882       tion  parameters  present  in  smb.conf.  Unlike  those  client  tools,
883       mount.cifs ignores smb.conf completely.
884

CONFIGURATION

886       The  primary mechanism for making configuration changes and for reading
887       debug information for the cifs vfs is via the Linux  /proc  filesystem.
888       In  the  directory  /proc/fs/cifs  are  various configuration files and
889       pseudo files which can display debug information and  performance  sta‐
890       tistics.  There  are  additional startup options such as maximum buffer
891       size and number of buffers which only may be set when the  kernel  cifs
892       vfs  (cifs.ko  module) is loaded. These can be seen by running the mod‐
893       info utility against the file cifs.ko which will list the options  that
894       may  be passed to cifs during module installation (device driver load).
895       For more information see the kernel file fs/cifs/README. When configur‐
896       ing dynamic tracing (trace-cmd) note that the list of SMB3 events which
897       can be enabled can be seen at: /sys/kernel/debug/tracing/events/cifs/.
898

SECURITY

900       The use of SMB2.1 or later (including the latest dialect  SMB3.1.1)  is
901       recommended  for  improved  security and SMB1 is no longer requested by
902       default at mount time. Old dialects such as CIFS  (SMB1,  ie  vers=1.0)
903       have  much  weaker security. Use of CIFS (SMB1) can be disabled by mod‐
904       probe cifs disable_legacy_dialects=y.
905

BUGS

907       Mounting using the CIFS URL specification is currently not supported.
908
909       The credentials file does not handle usernames or passwords with  lead‐
910       ing space.
911
912       Note  that  the typical response to a bug report is a suggestion to try
913       the latest version first. So please try doing that  first,  and  always
914       include which versions you use of relevant software when reporting bugs
915       (minimum: mount.cifs (try mount.cifs -V),  kernel  (see  /proc/version)
916       and server type you are trying to contact.
917

VERSION

919       This  man  page  is correct for version 2.18 of the cifs vfs filesystem
920       (roughly Linux kernel 5.0).
921

SEE ALSO

923       cifs.upcall(8), getcifsacl(1), setcifsacl(1)
924
925       Documentation/filesystems/cifs.txt and fs/cifs/README in the Linux ker‐
926       nel source tree may contain additional options and information.
927

AUTHOR

929       Steve French
930
931       The maintainer of the Linux cifs vfs is Steve French. The maintainer of
932       the cifs-utils suite of user space tools is Pavel Shilovsky. The  Linux
933       CIFS  Mailing  list  is  the preferred place to ask questions regarding
934       these programs.
935
936
937
938
939                                                                 MOUNT.CIFS(8)
Impressum