aboutsummaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
-rw-r--r--Makefile.am65
-rw-r--r--cifs.idmap.pod.in100
-rw-r--r--cifs.idmap.rst.in134
-rw-r--r--cifs.upcall.pod.in147
-rw-r--r--cifs.upcall.rst.in190
-rw-r--r--cifscreds.pod95
-rw-r--r--cifscreds.rst129
-rw-r--r--configure.ac10
-rw-r--r--getcifsacl.pod.in60
-rw-r--r--getcifsacl.rst.in86
-rw-r--r--idmapwb.pod.in26
-rw-r--r--idmapwb.rst.in37
-rw-r--r--mount.cifs.pod933
-rw-r--r--mount.cifs.rst860
-rw-r--r--pam_cifscreds.pod84
-rw-r--r--pam_cifscreds.rst116
-rw-r--r--setcifsacl.pod.in117
-rw-r--r--setcifsacl.rst.in185
18 files changed, 1769 insertions, 1605 deletions
diff --git a/Makefile.am b/Makefile.am
index 559ce08..30658e3 100644
--- a/Makefile.am
+++ b/Makefile.am
@@ -6,7 +6,7 @@ root_sbin_PROGRAMS = mount.cifs
mount_cifs_SOURCES = mount.cifs.c mtab.c resolve_host.c util.c
mount_cifs_LDADD = $(LIBCAP) $(CAPNG_LDADD) $(RT_LDADD)
include_HEADERS = cifsidmap.h
-pod_man_pages = mount.cifs.8
+rst_man_pages = mount.cifs.8
#
# Generate man pages troff source from POD format
@@ -14,25 +14,14 @@ pod_man_pages = mount.cifs.8
man_MANS=
-POD2MAN = pod2man -s $$(echo $@ | sed 's,.*\([1-9]\)$$,\1,' ) \
- -c 'System Administration Tools' -u -r '' --stderr $< $@
-
-%.1: %.pod
- $(POD2MAN)
-%.2: %.pod
- $(POD2MAN)
-%.3: %.pod
- $(POD2MAN)
-%.4: %.pod
- $(POD2MAN)
-%.5: %.pod
- $(POD2MAN)
-%.6: %.pod
- $(POD2MAN)
-%.7: %.pod
- $(POD2MAN)
-%.8: %.pod
- $(POD2MAN)
+SUFFIXES = .rst .1 .8
+
+RST2MAN = rst2man --syntax-highlight=none $< $@
+
+.rst.1:
+ $(RST2MAN)
+.rst.8:
+ $(RST2MAN)
CLEANFILES =
bin_PROGRAMS =
@@ -42,12 +31,12 @@ if CONFIG_CIFSUPCALL
sbin_PROGRAMS += cifs.upcall
cifs_upcall_SOURCES = cifs.upcall.c data_blob.c asn1.c spnego.c
cifs_upcall_LDADD = -ltalloc -lkeyutils $(KRB5_LDADD) $(CAPNG_LDADD)
-pod_man_pages += cifs.upcall.8
+rst_man_pages += cifs.upcall.8
#
# Fix the pathnames in manpages. To prevent @label@ being replaced by m4, we
# need to obfuscate the LHS of the regex (hence the trivial one character set).
#
-cifs.upcall.pod: cifs.upcall.pod.in
+cifs.upcall.rst: cifs.upcall.rst.in
$(SED) 's,[@]sbindir@,$(sbindir),' $(srcdir)/$@.in > $@-t && mv $@-t $@
endif
@@ -56,7 +45,7 @@ bin_PROGRAMS += cifscreds
cifscreds_SOURCES = cifscreds.c cifskey.c resolve_host.c util.c
cifscreds_LDADD = -lkeyutils
-pod_man_pages += cifscreds.1
+rst_man_pages += cifscreds.1
endif
@@ -64,9 +53,9 @@ if CONFIG_CIFSIDMAP
sbin_PROGRAMS += cifs.idmap
cifs_idmap_SOURCES = cifs.idmap.c idmap_plugin.c
cifs_idmap_LDADD = -lkeyutils -ldl
-pod_man_pages += cifs.idmap.8
-CLEANFILES += cifs.idmap.pod
-cifs.idmap.pod: cifs.idmap.pod.in
+rst_man_pages += cifs.idmap.8
+CLEANFILES += cifs.idmap.rst
+cifs.idmap.rst: cifs.idmap.rst.in
$(SED) -e 's,[@]sbindir@,$(sbindir),' -e 's,[@]pluginpath@,$(pluginpath),' $(srcdir)/$@.in > $@-t && mv $@-t $@
endif
@@ -75,18 +64,18 @@ bin_PROGRAMS += getcifsacl
getcifsacl_SOURCES = getcifsacl.c idmap_plugin.c
getcifsacl_LDADD = -ldl
-pod_man_pages += getcifsacl.1
-CLEANFILES += getcifsacl.pod
-getcifsacl.pod: getcifsacl.pod.in
+rst_man_pages += getcifsacl.1
+CLEANFILES += getcifsacl.rst
+getcifsacl.rst: getcifsacl.rst.in
$(SED) 's,[@]pluginpath@,$(pluginpath),' $(srcdir)/$@.in > $@-t && mv $@-t $@
bin_PROGRAMS += setcifsacl
setcifsacl_SOURCES = setcifsacl.c idmap_plugin.c
setcifsacl_LDADD = -ldl
-pod_man_pages += setcifsacl.1
-CLEANFILES += setcifsacl.pod
-setcifsacl.pod: setcifsacl.pod.in
+rst_man_pages += setcifsacl.1
+CLEANFILES += setcifsacl.rst
+setcifsacl.rst: setcifsacl.rst.in
$(SED) 's,[@]pluginpath@,$(pluginpath),' $(srcdir)/$@.in > $@-t && mv $@-t $@
endif
@@ -96,23 +85,23 @@ plugin_PROGRAMS = idmapwb.so
idmapwb.so: idmapwb.c
$(CC) $(DEFS) $(CFLAGS) $(AM_CFLAGS) $(WBCLIENT_CFLAGS) $(LDFLAGS) -shared -fpic -o $@ $+ $(WBCLIENT_LIBS)
-pod_man_pages += idmapwb.8
-CLEANFILES += idmapwb.pod
-idmapwb.pod: idmapwb.pod.in
+rst_man_pages += idmapwb.8
+CLEANFILES += idmapwb.rst
+idmapwb.rst: idmapwb.rst.in
$(SED) 's,[@]pluginpath@,$(pluginpath),' $(srcdir)/$@.in > $@-t && mv $@-t $@
endif
if CONFIG_PAM
pam_PROGRAMS = pam_cifscreds.so
-pod_man_pages += pam_cifscreds.8
+rst_man_pages += pam_cifscreds.8
pam_cifscreds.so: pam_cifscreds.c cifskey.c resolve_host.c util.c
$(CC) $(DEFS) $(CFLAGS) $(AM_CFLAGS) $(LDFLAGS) -shared -fpic -o $@ $+ -lpam -lkeyutils
endif
if CONFIG_MAN
-man_MANS += $(pod_man_pages)
-CLEANFILES += $(pod_man_pages)
+man_MANS += $(rst_man_pages)
+CLEANFILES += $(rst_man_pages)
endif
SUBDIRS = contrib
diff --git a/cifs.idmap.pod.in b/cifs.idmap.pod.in
deleted file mode 100644
index 9ff92c2..0000000
--- a/cifs.idmap.pod.in
+++ /dev/null
@@ -1,100 +0,0 @@
-# turn into a manpage with the following command:
-#
-# pod2man -s 1 -u -c '' -r '' --stderr cifs.idmap.pod cifs.idmap.8
-#
-
-=head1 NAME
-
-cifs.idmap - Userspace helper for mapping ids for Common Internet File System (CIFS)
-
-=head1 SYNOPSIS
-
-cifs.idmap [--help|-h] [--timeout|-t] [--version|-v] {keyid}
-
-=head1 DESCRIPTION
-
-This tool is part of the cifs-utils suite.
-
-B<cifs.idmap> is a userspace helper program for the linux CIFS client
-filesystem. There are a number of activities that the kernel cannot
-easily do itself. This program is a callout program that does these
-things for the kernel and then returns the result.
-
-B<cifs.idmap> is generally intended to be run when the kernel calls
-L<request-key(8)> for a particular key type. While it can be run
-directly from the command-line, it is not generally intended to be run
-that way.
-
-This program is only called if a share is mounted with the B<cifsacl>
-mount option. The kernel will only upcall to do this conversion if
-that mount option is specified.
-
-B<cifs.idmap> relies on a plugin to handle the ID mapping. If it can't
-find the plugin then it will not work properly. The plugin (or a
-symlink to it) must be at @pluginpath@.
-
-In the case where B<cifs.idmap> or the plugin are unavailable, file
-objects in a mounted share are assigned uid and gid of the credentials
-of the process that mounted the share. It is strongly recomemended to
-use mount options of uid and gid to specify a default uid and gid to
-map owner SIDs and group SIDs in this situation.
-
-=head1 OPTIONS
-
-=over
-
-=item B<--help|-h>
-
-Print the usage message and exit.
-
-=item B<--timeout|-t>
-
-Set the expiration timer, in seconds on the key. The default is 600
-seconds (10 minutes). Setting this to 0 will cause the key to never
-expire.
-
-=item B<--version|-v>
-
-Print version number and exit.
-
-=back
-
-=head1 CONFIGURATION FOR KEYCTL
-
-B<cifs.idmap> is designed to be called from the kernel via the
-request-key callout program. This requires that request-key be told
-where and how to call this program. Currently B<cifs.idmap> handles a
-key type of:
-
-=over
-
-=item B<cifs.idmap>
-
-This keytype is for mapping a SID to either an uid or a gid
-
-=back
-
-To make this program useful for CIFS, you will need to set up entry for it in
-L<request-key.conf(5)>. Here is an example of an entry for this key type:
-
- #OPERATION TYPE D C PROGRAM ARG1 ARG2...
- #========= ============= = = ================================
- create cifs.idmap * * @sbindir@/cifs.idmap %k
-
-See L<request-key.conf(5)> for more info on each field.
-
-=head1 NOTES
-
-Support for upcalls to cifs.idmap was initially introduced in the 3.0
-kernel.
-
-=head1 SEE ALSO
-
-L<request-key.conf(5)>, L<mount.cifs(8)>
-
-=head1 AUTHOR
-
-Shirish Pargaonkar wrote the cifs.idmap program.
-
-The Linux CIFS Mailing list is the preferred place to ask questions
-regarding these programs.
diff --git a/cifs.idmap.rst.in b/cifs.idmap.rst.in
new file mode 100644
index 0000000..91b585e
--- /dev/null
+++ b/cifs.idmap.rst.in
@@ -0,0 +1,134 @@
+==========
+cifs.idmap
+==========
+
+-----------------------------------------------------------------------
+Userspace helper for mapping ids for Common Internet File System (CIFS)
+-----------------------------------------------------------------------
+:Manual section: 8
+
+********
+SYNOPSIS
+********
+
+
+cifs.idmap [--help|-h] [--timeout|-t] [--version|-v] {keyid}
+
+
+***********
+DESCRIPTION
+***********
+
+
+This tool is part of the cifs-utils suite.
+
+\ **cifs.idmap**\ is a userspace helper program for the linux CIFS client
+filesystem. There are a number of activities that the kernel cannot
+easily do itself. This program is a callout program that does these
+things for the kernel and then returns the result.
+
+\ **cifs.idmap**\ is generally intended to be run when the kernel calls
+request-key(8) for a particular key type. While it can be run
+directly from the command-line, it is not generally intended to be run
+that way.
+
+This program is only called if a share is mounted with the \ **cifsacl**\
+mount option. The kernel will only upcall to do this conversion if
+that mount option is specified.
+
+\ **cifs.idmap**\ relies on a plugin to handle the ID mapping. If it can't
+find the plugin then it will not work properly. The plugin (or a
+symlink to it) must be at @pluginpath@.
+
+In the case where \ **cifs.idmap**\ or the plugin are unavailable, file
+objects in a mounted share are assigned uid and gid of the credentials
+of the process that mounted the share. It is strongly recomemended to
+use mount options of uid and gid to specify a default uid and gid to
+map owner SIDs and group SIDs in this situation.
+
+
+*******
+OPTIONS
+*******
+
+
+
+\ **--help|-h**\
+
+ Print the usage message and exit.
+
+
+
+\ **--timeout|-t**\
+
+ Set the expiration timer, in seconds on the key. The default is 600
+ seconds (10 minutes). Setting this to 0 will cause the key to never
+ expire.
+
+
+
+\ **--version|-v**\
+
+ Print version number and exit.
+
+
+
+
+************************
+CONFIGURATION FOR KEYCTL
+************************
+
+
+\ **cifs.idmap**\ is designed to be called from the kernel via the
+request-key callout program. This requires that request-key be told
+where and how to call this program. Currently \ **cifs.idmap**\ handles a
+key type of:
+
+
+\ **cifs.idmap**\
+
+ This keytype is for mapping a SID to either an uid or a gid
+
+
+
+To make this program useful for CIFS, you will need to set up entry for it in
+request-key.conf(5). Here is an example of an entry for this key type:
+
+
+.. code-block:: perl
+
+ #OPERATION TYPE D C PROGRAM ARG1 ARG2...
+ #========= ============= = = ================================
+ create cifs.idmap * * @sbindir@/cifs.idmap %k
+
+
+See request-key.conf(5) for more info on each field.
+
+
+*****
+NOTES
+*****
+
+
+Support for upcalls to cifs.idmap was initially introduced in the 3.0
+kernel.
+
+
+********
+SEE ALSO
+********
+
+
+request-key.conf(5), mount.cifs(8)
+
+
+******
+AUTHOR
+******
+
+
+Shirish Pargaonkar wrote the cifs.idmap program.
+
+The Linux CIFS Mailing list is the preferred place to ask questions
+regarding these programs.
+
diff --git a/cifs.upcall.pod.in b/cifs.upcall.pod.in
deleted file mode 100644
index ced3aed..0000000
--- a/cifs.upcall.pod.in
+++ /dev/null
@@ -1,147 +0,0 @@
-# turn into a manpage with the following command:
-#
-# pod2man -s 1 -u -c '' -r '' --stderr cifs.upcall.pod cifs.upcall.8
-#
-
-=head1 NAME
-
-cifs.upcall - Userspace upcall helper for Common Internet File System (CIFS)
-
-=head1 SYNOPSIS
-
- cifs.upcall [--trust-dns|-t] [--version|-v] [--legacy-uid|-l]
- [--krb5conf=/path/to/krb5.conf|-k /path/to/krb5.conf]
- [--keytab=/path/to/keytab|-K /path/to/keytab] {keyid}
-
-=head1 DESCRIPTION
-
-This tool is part of the cifs-utils suite.
-
-B<cifs.upcall> is a userspace helper program for the linux CIFS client
-filesystem. There are a number of activities that the kernel cannot
-easily do itself. This program is a callout program that does these
-things for the kernel and then returns the result.
-
-B<cifs.upcall> is generally intended to be run when the kernel calls
-L<request-key(8)> for a particular key type. While it can be run
-directly from the command-line, it's not generally intended to be run
-that way.
-
-=head1 OPTIONS
-
-=over
-
-=item B<-c>
-
-This option is deprecated and is currently ignored.
-
-=item B<--no-env-probe|-E>
-
-Normally, B<cifs.upcall> will probe the environment variable space of
-the process that initiated the upcall in order to fetch the value of
-C<$KRB5CCNAME>. This can assist the program with finding credential
-caches in non-default locations. If this option is set, then the
-program won't do this and will rely on finding credcaches in the
-default locations specified in F<krb5.conf>. Note that this is never
-performed when the uid is 0. The default credcache location is always
-used when the uid is 0, regardless of the environment variable setting
-in the process.
-
-=item B<--krb5conf=F</path/to/krb5.conf>|-k F</path/to/krb5.conf>>
-
-This option allows administrators to set an alternate location for the
-F<krb5.conf> file that B<cifs.upcall> will use.
-
-=item B<--keytab=F</path/to/keytab>|-K F</path/to/keytab>>
-
-This option allows administrators to specify a keytab file to be
-used. When a user has no credential cache already established,
-B<cifs.upcall> will attempt to use this keytab to acquire them. The
-default is the system-wide keytab F</etc/krb5.keytab>.
-
-=item B<--trust-dns|-t>
-
-With krb5 upcalls, the name used as the host portion of the service
-principal defaults to the hostname portion of the UNC. This option
-allows the upcall program to reverse resolve the network address of
-the server in order to get the hostname.
-
-This is less secure than not trusting DNS. When using this option,
-it's possible that an attacker could get control of DNS and trick the
-client into mounting a different server altogether. It's preferable to
-instead add server principals to the KDC for every possible hostname,
-but this option exists for cases where that isn't possible. The
-default is to not trust reverse hostname lookups in this fashion.
-
-=item B<--legacy-uid|-l>
-
-Traditionally, the kernel has sent only a single uid= parameter to the
-upcall for the SPNEGO upcall that's used to determine what user's
-credential cache to use. This parameter is affected by the B<uid=>
-mount option, which also governs the ownership of files on the mount.
-
-Newer kernels send a creduid= option as well, which contains what uid
-it thinks actually owns the credentials that it's looking for. At
-mount time, this is generally set to the real uid of the user doing
-the mount. For multisession mounts, it's set to the fsuid of the mount
-user. Set this option if you want cifs.upcall to use the older B<uid=>
-parameter instead of the creduid= parameter.
-
-=item B<--version|-v>
-
-Print version number and exit.
-
-=back
-
-=head1 CONFIGURATION FOR KEYCTL
-
-B<cifs.upcall> is designed to be called from the kernel via the
-request-key callout program. This requires that request-key be told
-where and how to call this program. The current B<cifs.upcall>
-program handles two different key types:
-
-=over
-
-=item B<cifs.spnego>
-
-This keytype is for retrieving kerberos session keys
-
-=item B<dns_resolver>
-
-This key type is for resolving hostnames into IP addresses. Support
-for this key type may eventually be deprecated (see below).
-
-To make this program useful for CIFS, you'll need to set up entries
-for them in L<request-key.conf(5)>. Here's an example of an entry for
-each key type:
-
- #OPERATION TYPE D C PROGRAM ARG1 ARG2...
- #========= ============= = = ================================
- create cifs.spnego * * @sbindir@/cifs.upcall %k
- create dns_resolver * * @sbindir@/cifs.upcall %k
-
-See L<request-key.conf(5)> for more info on each field.
-
-The keyutils package has also started including a dns_resolver
-handling program as well that is preferred over the one in
-B<cifs.upcall.> If you are using a keyutils version equal to or
-greater than 1.5, you should use C<key.dns_resolver> to handle the
-C<dns_resolver> keytype instead of B<cifs.upcall>. See
-L<key.dns_resolver(8)> for more info.
-
-=back
-
-=head1 SEE ALSO
-
-L<request-key.conf(5)>, L<mount.cifs(8)>, L<key.dns_resolver(8)>
-
-=head1 AUTHOR
-
-Igor Mammedov wrote the cifs.upcall program.
-
-Jeff Layton authored this manpage.
-
-The maintainer of the Linux CIFS VFS is Steve French.
-
-The Linux CIFS Mailing list is the preferred place to ask questions
-regarding these programs.
diff --git a/cifs.upcall.rst.in b/cifs.upcall.rst.in
new file mode 100644
index 0000000..8f4ee62
--- /dev/null
+++ b/cifs.upcall.rst.in
@@ -0,0 +1,190 @@
+===========
+cifs.upcall
+===========
+
+--------------------------------------------------------------
+Userspace upcall helper for Common Internet File System (CIFS)
+--------------------------------------------------------------
+:Manual section: 8
+
+
+********
+SYNOPSIS
+********
+
+.. code-block:: perl
+
+ cifs.upcall [--trust-dns|-t] [--version|-v] [--legacy-uid|-l]
+ [--krb5conf=/path/to/krb5.conf|-k /path/to/krb5.conf]
+ [--keytab=/path/to/keytab|-K /path/to/keytab] {keyid}
+
+
+
+***********
+DESCRIPTION
+***********
+
+
+This tool is part of the cifs-utils suite.
+
+\ **cifs.upcall**\ is a userspace helper program for the linux CIFS client
+filesystem. There are a number of activities that the kernel cannot
+easily do itself. This program is a callout program that does these
+things for the kernel and then returns the result.
+
+\ **cifs.upcall**\ is generally intended to be run when the kernel calls
+request-key(8) for a particular key type. While it can be run
+directly from the command-line, it's not generally intended to be run
+that way.
+
+
+*******
+OPTIONS
+*******
+
+
+
+\ **-c**\
+
+ This option is deprecated and is currently ignored.
+
+
+
+\ **--no-env-probe|-E**\
+
+ Normally, \ **cifs.upcall**\ will probe the environment variable space of
+ the process that initiated the upcall in order to fetch the value of
+ \ ``$KRB5CCNAME``\ . This can assist the program with finding credential
+ caches in non-default locations. If this option is set, then the
+ program won't do this and will rely on finding credcaches in the
+ default locations specified in \ *krb5.conf*\ . Note that this is never
+ performed when the uid is 0. The default credcache location is always
+ used when the uid is 0, regardless of the environment variable setting
+ in the process.
+
+
+
+\ **--krb5conf|-k=/path/to/krb5.conf**\
+
+ This option allows administrators to set an alternate location for the
+ \ *krb5.conf*\ file that \ **cifs.upcall**\ will use.
+
+
+
+\ **--keytab=|-K=/path/to/keytab**\
+
+ This option allows administrators to specify a keytab file to be
+ used. When a user has no credential cache already established,
+ \ **cifs.upcall**\ will attempt to use this keytab to acquire them. The
+ default is the system-wide keytab \ */etc/krb5.keytab*\ .
+
+
+
+\ **--trust-dns|-t**\
+
+ With krb5 upcalls, the name used as the host portion of the service
+ principal defaults to the hostname portion of the UNC. This option
+ allows the upcall program to reverse resolve the network address of
+ the server in order to get the hostname.
+
+ This is less secure than not trusting DNS. When using this option,
+ it's possible that an attacker could get control of DNS and trick the
+ client into mounting a different server altogether. It's preferable to
+ instead add server principals to the KDC for every possible hostname,
+ but this option exists for cases where that isn't possible. The
+ default is to not trust reverse hostname lookups in this fashion.
+
+
+
+\ **--legacy-uid|-l**\
+
+ Traditionally, the kernel has sent only a single uid= parameter to the
+ upcall for the SPNEGO upcall that's used to determine what user's
+ credential cache to use. This parameter is affected by the \ **uid=**\
+ mount option, which also governs the ownership of files on the mount.
+
+ Newer kernels send a creduid= option as well, which contains what uid
+ it thinks actually owns the credentials that it's looking for. At
+ mount time, this is generally set to the real uid of the user doing
+ the mount. For multisession mounts, it's set to the fsuid of the mount
+ user. Set this option if you want cifs.upcall to use the older \ **uid=**\
+ parameter instead of the creduid= parameter.
+
+
+
+\ **--version|-v**\
+
+ Print version number and exit.
+
+
+
+
+************************
+CONFIGURATION FOR KEYCTL
+************************
+
+
+\ **cifs.upcall**\ is designed to be called from the kernel via the
+request-key callout program. This requires that request-key be told
+where and how to call this program. The current \ **cifs.upcall**\
+program handles two different key types:
+
+
+\ **cifs.spnego**\
+
+ This keytype is for retrieving kerberos session keys
+
+
+
+\ **dns_resolver**\
+
+ This key type is for resolving hostnames into IP addresses. Support
+ for this key type may eventually be deprecated (see below).
+
+ To make this program useful for CIFS, you'll need to set up entries
+ for them in request-key.conf(5). Here's an example of an entry for
+ each key type:
+
+
+ .. code-block:: perl
+
+ #OPERATION TYPE D C PROGRAM ARG1 ARG2...
+ #========= ============= = = ================================
+ create cifs.spnego * * @sbindir@/cifs.upcall %k
+ create dns_resolver * * @sbindir@/cifs.upcall %k
+
+
+ See request-key.conf(5) for more info on each field.
+
+ The keyutils package has also started including a dns_resolver
+ handling program as well that is preferred over the one in
+ \ **cifs.upcall.**\ If you are using a keyutils version equal to or
+ greater than 1.5, you should use \ ``key.dns_resolver``\ to handle the
+ \ ``dns_resolver``\ keytype instead of \ **cifs.upcall**\ . See
+ key.dns_resolver(8) for more info.
+
+
+
+
+********
+SEE ALSO
+********
+
+
+request-key.conf(5), mount.cifs(8), key.dns_resolver(8)
+
+
+******
+AUTHOR
+******
+
+
+Igor Mammedov wrote the cifs.upcall program.
+
+Jeff Layton authored this manpage.
+
+The maintainer of the Linux CIFS VFS is Steve French.
+
+The Linux CIFS Mailing list is the preferred place to ask questions
+regarding these programs.
+
diff --git a/cifscreds.pod b/cifscreds.pod
deleted file mode 100644
index c3bafb5..0000000
--- a/cifscreds.pod
+++ /dev/null
@@ -1,95 +0,0 @@
-# turn into a manpage with the following command:
-#
-# pod2man -s 1 -c '' -r '' --stderr cifscreds.pod > cifscreds.1
-#
-
-=head1 NAME
-
-cifscreds - manage NTLM credentials in kernel keyring
-
-=head1 SYNOPSIS
-
-cifscreds add|clear|clearall|update [-u username] [-d] host|domain
-
-=head1 DESCRIPTION
-
-The B<cifscreds> program is a tool for managing credentials (username
-and password) for the purpose of establishing sessions in multiuser
-mounts.
-
-When a cifs filesystem is mounted with the "multiuser" option, and does
-not use krb5 authentication, it needs to be able to get the credentials
-for each user from somewhere. The B<cifscreds> program is the tool used
-to provide these credentials to the kernel.
-
-The first non-option argument to cifscreds is a command (see the
-B<COMMANDS> section below). The second non-option argument is a hostname
-or address, or an NT domain name.
-
-=head1 COMMANDS
-
-=over
-
-=item B<add>
-
-Add credentials to the kernel to be used for connecting to the given server, or servers in the given domain.
-
-=item B<clear>
-
-Clear credentials for a particular host or domain from the kernel.
-
-=item B<clearall>
-
-Clear all cifs credentials from the kernel.
-
-=item B<update>
-
-Update stored credentials in the kernel with a new username and
-password.
-
-=back
-
-=head1 OPTIONS
-
-=over
-
-=item B<-d>, B<--domain>
-
-The provided host/domain argument is a NT domainname.
-
-Ordinarily the second argument provided to cifscreds is treated as a
-hostname or IP address. This option causes the cifscreds program to
-treat that argument as an NT domainname instead.
-
-If there are not host specific credentials for the mounted server, then
-the kernel will next look for a set of domain credentials equivalent to
-the domain= option provided at mount time.
-
-=item B<-u>, B<--username>
-
-Ordinarily, the username is derived from the unix username of the user
-adding the credentials. This option allows the user to substitute a
-different username.
-
-=back
-
-=head1 NOTES
-
-The cifscreds utility requires a kernel built with support for the
-B<login> key type. That key type was added in v3.3 in mainline Linux
-kernels.
-
-Since B<cifscreds> adds keys to the session keyring, it is highly
-recommended that one use B<pam_keyinit> to ensure that a session keyring
-is established at login time.
-
-=head1 SEE ALSO
-
-pam_keyinit(8)
-
-=head1 AUTHORS
-
-The cifscreds program was originally developed by Igor Druzhinin
-<jaxbrigs@gmail.com>. This manpage and a redesign of the code was done
-by Jeff Layton <jlayton@samba.org>.
-
diff --git a/cifscreds.rst b/cifscreds.rst
new file mode 100644
index 0000000..5c2a195
--- /dev/null
+++ b/cifscreds.rst
@@ -0,0 +1,129 @@
+=========
+cifscreds
+=========
+
+-----------------------------------------
+manage NTLM credentials in kernel keyring
+-----------------------------------------
+
+:Manual section: 1
+
+********
+SYNOPSIS
+********
+
+
+cifscreds add|clear|clearall|update [-u username] [-d] host|domain
+
+
+***********
+DESCRIPTION
+***********
+
+
+The \ **cifscreds**\ program is a tool for managing credentials (username
+and password) for the purpose of establishing sessions in multiuser
+mounts.
+
+When a cifs filesystem is mounted with the "multiuser" option, and does
+not use krb5 authentication, it needs to be able to get the credentials
+for each user from somewhere. The \ **cifscreds**\ program is the tool used
+to provide these credentials to the kernel.
+
+The first non-option argument to cifscreds is a command (see the
+\ **COMMANDS**\ section below). The second non-option argument is a hostname
+or address, or an NT domain name.
+
+
+********
+COMMANDS
+********
+
+
+
+\ **add**\
+
+ Add credentials to the kernel to be used for connecting to the given server, or servers in the given domain.
+
+
+
+\ **clear**\
+
+ Clear credentials for a particular host or domain from the kernel.
+
+
+
+\ **clearall**\
+
+ Clear all cifs credentials from the kernel.
+
+
+
+\ **update**\
+
+ Update stored credentials in the kernel with a new username and
+ password.
+
+
+
+
+*******
+OPTIONS
+*******
+
+
+
+\ **-d**\ , \ **--domain**\
+
+ The provided host/domain argument is a NT domainname.
+
+ Ordinarily the second argument provided to cifscreds is treated as a
+ hostname or IP address. This option causes the cifscreds program to
+ treat that argument as an NT domainname instead.
+
+ If there are not host specific credentials for the mounted server, then
+ the kernel will next look for a set of domain credentials equivalent to
+ the domain= option provided at mount time.
+
+
+
+\ **-u**\ , \ **--username**\
+
+ Ordinarily, the username is derived from the unix username of the user
+ adding the credentials. This option allows the user to substitute a
+ different username.
+
+
+
+
+*****
+NOTES
+*****
+
+
+The cifscreds utility requires a kernel built with support for the
+\ **login**\ key type. That key type was added in v3.3 in mainline Linux
+kernels.
+
+Since \ **cifscreds**\ adds keys to the session keyring, it is highly
+recommended that one use \ **pam_keyinit**\ to ensure that a session keyring
+is established at login time.
+
+
+********
+SEE ALSO
+********
+
+
+pam_keyinit(8)
+
+
+*******
+AUTHORS
+*******
+
+
+The cifscreds program was originally developed by Igor Druzhinin
+<jaxbrigs@gmail.com>. This manpage and a redesign of the code was done
+by Jeff Layton <jlayton@samba.org>.
+
diff --git a/configure.ac b/configure.ac
index 0e118a9..52b49a7 100644
--- a/configure.ac
+++ b/configure.ac
@@ -250,14 +250,14 @@ if test $enable_systemd != "no"; then
AC_DEFINE(ENABLE_SYSTEMD, 1, [Enable systemd specific behavior for mount.cifs])
fi
-# if docs are not disabled, check if pod2man is available
+# if docs are not disabled, check if rst2man is available
if test $enable_man != "no"; then
- AC_CHECK_PROG(have_pod2man, pod2man, yes, no)
- if test $have_pod2man = "no"; then
+ AC_CHECK_PROG(have_rst2man, rst2man, yes, no)
+ if test $have_rst2man = "no"; then
if test $enable_man = "yes"; then
- AC_MSG_ERROR([pod2man not found: cannot generate man pages, consider installing perl.])
+ AC_MSG_ERROR([rst2man not found: cannot generate man pages, consider installing perl.])
else
- AC_MSG_WARN([pod2man not found: cannot generate man pages, consider installing perl. Disabling man page generation.])
+ AC_MSG_WARN([rst2man not found: cannot generate man pages, consider installing perl. Disabling man page generation.])
enable_man="no"
fi
else
diff --git a/getcifsacl.pod.in b/getcifsacl.pod.in
deleted file mode 100644
index 3099b6c..0000000
--- a/getcifsacl.pod.in
+++ /dev/null
@@ -1,60 +0,0 @@
-# turn into a manpage with the following command:
-#
-# pod2man -s 1 -u -c '' -r '' --stderr getcifsacl.pod getcifsacl.1
-#
-
-=head1 NAME
-
-getcifsacl - Userspace helper to display an ACL in a security descriptor for Common Internet File System (CIFS)
-
-=head1 SYNOPSIS
-
-getcifsacl [-v|-r] {file system object}
-
-=head1 DESCRIPTION
-
-This tool is part of the cifs-utils suite.
-
-getcifsacl is a userspace helper program for the Linux CIFS client
-file system. It is intended to display a security descriptor including
-ACL for a file system object.
-
-This program uses a plugin to handle the mapping of SIDs to user and
-group names. F<@pluginpath@> should be a symlink that points to the
-correct plugin to use.
-
-Fields of an ACE such as SID, type, flags, and mask are displayed
-separated by /. Numeric values of type, flags, and mask are displayed
-in hexadecimal format.
-
-=head1 OPTIONS
-
-=over
-
-=item B<-v>
-
-Print version number and exit.
-
-=item B<-r>
-
-Display a security descriptor in raw mode. Values such as type and
-flags are displayed in hexadecimal format, a SID is not mapped to a
-name.
-
-=back
-
-=head1 NOTES
-
-Kernel support for getcifsacl/setcifsacl utilities was initially
-introduced in the 2.6.37 kernel.
-
-=head1 SEE ALSO
-
-L<mount.cifs(8)>, L<setcifsacl(1)>
-
-=head1 AUTHOR
-
-Shirish Pargaonkar wrote the getcifsacl program.
-
-The Linux CIFS Mailing list is the preferred place to ask questions
-regarding these programs.
diff --git a/getcifsacl.rst.in b/getcifsacl.rst.in
new file mode 100644
index 0000000..42af258
--- /dev/null
+++ b/getcifsacl.rst.in
@@ -0,0 +1,86 @@
+==========
+getcifsacl
+==========
+
+--------------------------------------------------------------------------------------------------
+Userspace helper to display an ACL in a security descriptor for Common Internet File System (CIFS)
+--------------------------------------------------------------------------------------------------
+:Manual section: 1
+
+
+********
+SYNOPSIS
+********
+
+
+getcifsacl [-v|-r] {file system object}
+
+
+***********
+DESCRIPTION
+***********
+
+
+This tool is part of the cifs-utils suite.
+
+getcifsacl is a userspace helper program for the Linux CIFS client
+file system. It is intended to display a security descriptor including
+ACL for a file system object.
+
+This program uses a plugin to handle the mapping of SIDs to user and
+group names. \ *@pluginpath@*\ should be a symlink that points to the
+correct plugin to use.
+
+Fields of an ACE such as SID, type, flags, and mask are displayed
+separated by /. Numeric values of type, flags, and mask are displayed
+in hexadecimal format.
+
+
+*******
+OPTIONS
+*******
+
+
+
+\ **-v**\
+
+ Print version number and exit.
+
+
+
+\ **-r**\
+
+ Display a security descriptor in raw mode. Values such as type and
+ flags are displayed in hexadecimal format, a SID is not mapped to a
+ name.
+
+
+
+
+*****
+NOTES
+*****
+
+
+Kernel support for getcifsacl/setcifsacl utilities was initially
+introduced in the 2.6.37 kernel.
+
+
+********
+SEE ALSO
+********
+
+
+mount.cifs(8), setcifsacl(1)
+
+
+******
+AUTHOR
+******
+
+
+Shirish Pargaonkar wrote the getcifsacl program.
+
+The Linux CIFS Mailing list is the preferred place to ask questions
+regarding these programs.
+
diff --git a/idmapwb.pod.in b/idmapwb.pod.in
deleted file mode 100644
index 4cc2b5a..0000000
--- a/idmapwb.pod.in
+++ /dev/null
@@ -1,26 +0,0 @@
-# turn into a manpage with the following command:
-#
-# pod2man -s 8 -c '' -r '' --stderr idmapwb.pod > idmapwb.8.in
-#
-
-=head1 NAME
-
-idmapwb.so - winbind ID mapping plugin for cifs-utils
-
-=head1 DESCRIPTION
-
-This plugin allows the utilities in cifs-utils to work in conjuction with
-the winbind facility of Samba suite. It handles several functions including
-mapping UID and GID to SIDs and vice versa.
-
-Utilities are usually configured to use the correct plugin by creating a
-symlink at @pluginpath@ that points to the correct plugin that you wish
-to use.
-
-This plugin requires that B<winbindd(8)> be properly configured and running.
-
-=head1 SEE ALSO
-getcifsacl(1), setcifsacl(1), cifs.idmap(8), samba(7), smb.conf(5), winbindd(8)
-
-=head1 AUTHOR
-idmapwb.so was written by Jeff Layton <jlayton@samba.org>
diff --git a/idmapwb.rst.in b/idmapwb.rst.in
new file mode 100644
index 0000000..4d7fd62
--- /dev/null
+++ b/idmapwb.rst.in
@@ -0,0 +1,37 @@
+==========
+idmapwb.so
+==========
+
+----------------------------------------
+winbind ID mapping plugin for cifs-utils
+----------------------------------------
+:Manual section: 8
+
+
+***********
+DESCRIPTION
+***********
+
+
+This plugin allows the utilities in cifs-utils to work in conjuction with
+the winbind facility of Samba suite. It handles several functions including
+mapping UID and GID to SIDs and vice versa.
+
+Utilities are usually configured to use the correct plugin by creating a
+symlink at @pluginpath@ that points to the correct plugin that you wish
+to use.
+
+This plugin requires that \ **winbindd(8)**\ be properly configured and running.
+
+
+*******************************************************************************
+SEE ALSO
+*******************************************************************************
+getcifsacl(1), setcifsacl(1), cifs.idmap(8), samba(7), smb.conf(5), winbindd(8)
+
+
+
+*****************************************************************
+AUTHOR
+*****************************************************************
+idmapwb.so was written by Jeff Layton <jlayton@samba.org>
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.
diff --git a/mount.cifs.rst b/mount.cifs.rst
new file mode 100644
index 0000000..9714f79
--- /dev/null
+++ b/mount.cifs.rst
@@ -0,0 +1,860 @@
+==========
+mount.cifs
+==========
+
+--------------------------------------------------
+mount using the Common Internet File System (CIFS)
+--------------------------------------------------
+:Manual section: 8
+
+********
+SYNOPSIS
+********
+
+ mount.cifs {service} {mount-point} [-o options]
+
+This tool is part of the cifs-utils suite.
+
+``mount.cifs`` mounts a Linux CIFS filesystem. It is usually invoked
+indirectly by the mount(8) command when using the "-t cifs"
+option. This command only works in Linux, and the kernel must support
+the cifs filesystem. The CIFS protocol is the successor to the SMB
+protocol and is supported by most Windows servers and many other
+commercial servers and Network Attached Storage appliances as well as
+by the popular Open Source server Samba.
+
+The mount.cifs utility attaches the UNC name (exported network
+resource) specified as service (using ``//server/share`` syntax, where
+"server" is the server name or IP address and "share" is the name of
+the share) to the local directory mount-point.
+
+Options to mount.cifs are specified as a comma-separated list of
+``key=value`` pairs. It is possible to send options other than those
+listed here, assuming that the cifs filesystem kernel module
+(``cifs.ko``) supports them. Unrecognized cifs mount options passed to
+the cifs vfs kernel code will be logged to the kernel log.
+
+``mount.cifs`` causes the cifs vfs to launch a thread named
+cifsd. After mounting it keeps running until the mounted resource is
+unmounted (usually via the ``umount`` utility).
+
+``mount.cifs -V`` command displays the version of cifs mount helper.
+
+``modinfo cifs`` command displays the version of cifs module.
+
+
+*******
+OPTIONS
+*******
+
+
+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 ``user%password`` or ``workgroup/user`` or
+ ``workgroup/user%password`` to allow the password and workgroup to
+ be specified as part of the username. Support for those alternate
+ username formats is now deprecated and should no longer be
+ used. Users should use the discrete ``password=`` and ``domain=`` to
+ specify those values. While some versions of the cifs kernel module
+ accept ``user=`` as an abbreviation for this option, its use can
+ confuse the standard mount program into thinking that this is a
+ non-superuser mount. It is therefore recommended to use the full
+ ``username=`` option name.
+
+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.
+
+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 ``/etc/fstab`` . Be sure to protect any credentials file
+ properly.
+
+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 `FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS`_
+ below for more information.
+
+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
+ `FILE AND DIRECTORY OWNERSHIP AND PERMISSIONS`_ below for more information.
+
+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.
+
+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.
+
+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.
+
+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.
+
+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.
+
+servern=arg
+ Synonym for ``servernetbiosname``
+
+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.
+
+file_mode=arg
+ If the server does not support the CIFS Unix extensions this overrides
+ the default file mode.
+
+dir_mode=arg
+ If the server does not support the CIFS Unix extensions this overrides
+ the default mode for directories.
+
+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.
+
+domain=arg
+ sets the domain (workgroup) of the user.
+
+guest
+ don't prompt for a password.
+
+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 ``iocharset`` is not specified then the ``nls_default`` specified
+ during the local client kernel build will be used. If server does not
+ support Unicode, this parameter is unused.
+
+ro
+ mount read-only.
+
+rw
+ mount read-write.
+
+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).
+
+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.
+
+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.
+
+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).
+
+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.
+
+cache=arg
+ Cache mode. See the section below on `CACHE COHERENCY`_ for
+ details. Allowed values are:
+
+ - ``none`` - do not cache file data at all
+ - ``strict`` - follow the CIFS/SMB2 protocol strictly
+ - ``loose`` - allow loose caching semantics
+
+ The default in kernels prior to 3.7 was ``loose``. As of kernel 3.7 the
+ default is ``strict``.
+
+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
+ ``cache=none`` instead on more recent kernels.
+
+strictcache
+ Use for switching on strict cache mode. In this mode the client reads
+ from the cache all the time it has *Oplock Level II* , otherwise -
+ read from the server. As for write - the client stores a data in the
+ cache in *Exclusive Oplock* case, otherwise - write directly to the
+ server.
+
+ This option is will be deprecated in 3.7. Users should use
+ ``cache=strict`` instead on more recent kernels.
+
+rwpidforward
+ Forward pid of a process who opened a file to any read or write
+ operation on that file. This prevent applications like wine(1) from
+ failing on read and write if we use mandatory brlock style.
+
+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 ``mapchars`` mount option may not be accessible
+ if the share is mounted without that option.
+
+nomapchars
+ (default) Do not translate any of these seven characters.
+
+intr
+ currently unimplemented.
+
+nointr
+ (default) currently unimplemented.
+
+hard
+ The program accessing a file on the cifs mounted file system will hang
+ when the server crashes.
+
+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.
+
+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 ``CIFS_XATTR`` and then ``CIFS_POSIX`` support in the CIFS
+ configuration options when building the cifs module. POSIX ACL support
+ can be disabled on a per mount basis by specifying ``noacl`` on mount.
+
+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 section on `CIFS/NTFS ACL, SID/UID/GID MAPPING, SECURITY DESCRIPTORS`_
+ for more information.
+
+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 `ACCESSING FILES WITH BACKUP INTENT`_ for more details.
+
+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 `ACCESSING FILES WITH BACKUP INTENT`_ for more details.
+
+nocase
+ Request case insensitive path name matching (case sensitive is the default if the
+ server supports it).
+
+ignorecase
+ Synonym for ``nocase``.
+
+sec=arg
+ Security mode. Allowed values are:
+
+ - ``none`` - attempt to connection as a null user (no name)
+ - ``krb5`` - Use Kerberos version 5 authentication
+ - ``krb5i`` - Use Kerberos authentication and forcibly enable packet signing
+ - ``ntlm`` - Use NTLM password hashing
+ - ``ntlmi`` - Use NTLM password hashing and force packet signing
+ - ``ntlmv2`` - Use NTLMv2 password hashing
+ - ``ntlmv2i`` - Use NTLMv2 password hashing and force packet signing
+ - ``ntlmssp`` - Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message
+ - ``ntlmsspi`` - Use NTLMv2 password hashing encapsulated in Raw NTLMSSP message, and force packet signing
+
+ The default in mainline kernel versions prior to v3.8 was
+ ``sec=ntlm``. In v3.8, the default was changed to ``sec=ntlmssp``.
+
+ If the server requires signing during protocol negotiation, then it
+ may be enabled automatically. Packet signing may also be enabled
+ automatically if it's enabled in */proc/fs/cifs/SecurityFlags*.
+
+seal
+ Request encryption at the SMB layer. Encryption is only supported in
+ SMBv3 and above. The encryption algorithm used is AES-128-CCM.
+
+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).
+
+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
+ ``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.
+
+mfsymlinks
+ Enable support for Minshall+French symlinks (see
+ `http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks <http://wiki.samba.org/index.php/UNIX_Extensions#Minshall.2BFrench_symlinks>`_). This
+ option is ignored when specified together with the ``sfu``
+ option. Minshall+French symlinks are used even if the server supports
+ the CIFS Unix Extensions.
+
+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.
+
+noserverino
+ Client generates inode numbers itself rather than using the actual
+ ones from the server.
+
+ See section `INODE NUMBERS`_ for more information.
+
+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 `INODE NUMBERS`_ for more information.
+
+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.
+
+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 ``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.
+
+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.
+
+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.
+
+ **NOTE**: This feature is available only in the recent kernels that
+ have been built with the kernel config option
+ ``CONFIG_CIFS_FSCACHE``. You also need to have ``cachefilesd``
+ daemon installed and running to make the cache operational.
+
+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 ``sec=`` options that don't require passwords.
+
+ With this change, it's feasible for the server to handle permissions
+ enforcement, so this option also implies ``noperm`` . Furthermore, when
+ unix extensions aren't in use and the administrator has not overridden
+ ownership using the ``uid=`` or ``gid=`` options, ownership of files is
+ presented as the current user accessing the share.
+
+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 ``actimeo`` value is a positive
+ integer that can hold values between 0 and a maximum value of 2^30 \*
+ HZ (frequency of timer interrupt) setting.
+
+noposixpaths
+ 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.
+
+posixpaths
+ Inverse of ``noposixpaths`` .
+
+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.
+
+vers=arg
+ SMB protocol version. Allowed values are:
+
+ - 1.0 - The classic CIFS/SMBv1 protocol. This is the default.
+ - 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.
+ - 2.1 - The SMBv2.1 protocol that was introduced in Microsoft Windows 7 and Windows Server 2008R2.
+ - 3.0 - The SMBv3.0 protocol that was introduced in Microsoft Windows 8 and Windows Server 2012.
+ - 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.
+
+--verbose
+ Print additional debugging information for the mount. Note that this
+ parameter must be specified before the ``-o`` . For example::
+
+ mount -t cifs //server/share /mnt --verbose -o user=username
+
+
+*********************************
+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.
+
+``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:
+
+`http://technet.microsoft.com/en-us/library/bb463216.aspx <http://technet.microsoft.com/en-us/library/bb463216.aspx>`_
+
+In order to map SIDs to/from UIDs and GIDs, the following is required:
+
+- a kernel upcall to the ``cifs.idmap`` utility set up via request-key.conf(5)
+- winbind support configured via nsswitch.conf(5) and smb.conf(5)
+
+Please refer to the respective manpages of cifs.idmap(8) and
+winbindd(8) for more information.
+
+Security descriptors for a file object can be retrieved and set
+directly using extended attribute named ``system.cifs_acl``. The
+security descriptors presented via this interface are "raw" blobs of
+data and need a userspace utility to either parse and format or to
+assemble it such as getcifsacl(1) and setcifsacl(1)
+respectively.
+
+Some of the things to consider while using this mount option:
+
+- There may be an increased latency when handling metadata due to
+ additional requests to get and set security descriptors.
+- The mapping between a CIFS/NTFS ACL and POSIX file permission bits
+ is imperfect and some ACL information may be lost in the
+ translation.
+- 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.
+
+**********************************
+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 *Backup Operators*. Thus, when
+this user attempts to open a file with the backup intent, open request
+is sent by setting the bit ``FILE_OPEN_FOR_BACKUP_INTENT`` as one of
+the ``CreateOptions``.
+
+As an example, on a Windows server, a user named *testuser*, cannot open
+this file with such a security descriptor::
+
+ REVISION:0x1
+ CONTROL:0x9404
+ OWNER:Administrator
+ GROUP:Domain Users
+ ACL:Administrator:ALLOWED/0x0/FULL
+
+But the user *testuser*, if it becomes part of the *Backup Operators*
+group, can open the file with the backup intent.
+
+Any user on the client side who can authenticate as such a user on the
+server, can access the files with the backup intent. But it is
+desirable and preferable for security reasons amongst many, to
+restrict this special right.
+
+The mount option ``backupuid`` is used to restrict this special right
+to a user which is specified by either a name or an id. The mount
+option ``backupgid`` is used to restrict this special right to the
+users in a group which is specified by either a name or an id. Only
+users matching either backupuid or backupgid shall attempt to access
+files with backup intent. These two mount options can be used
+together.
+
+********************************************
+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 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.
+
+*********************
+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 noexec and nosuid mount flags are enabled. When
+installed as a setuid program, the program follows the conventions set
+forth by the mount program for user mounts, with the added restriction
+that users must be able to chdir() into the mountpoint prior to the
+mount in order to be able to mount onto it.
+
+Some samba client tools like smbclient(8) honour client-side
+configuration parameters present in *smb.conf*. Unlike those client
+tools, ``mount.cifs`` ignores *smb.conf* completely.
+
+*************
+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 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.
+ \ No newline at end of file
diff --git a/pam_cifscreds.pod b/pam_cifscreds.pod
deleted file mode 100644
index b04ee71..0000000
--- a/pam_cifscreds.pod
+++ /dev/null
@@ -1,84 +0,0 @@
-# turn into a manpage with the following command:
-#
-# pod2man -s 8 -u -c '' -r '' --stderr pam_cifscreds.pod pam_cifscreds.8
-#
-
-=head1 NAME
-
-pam_cifscreds - PAM module to manage NTLM credentials in kernel keyring
-
-=head1 SYNOPSIS
-
-Edit the PAM configuration files for the systems that you want to
-automatically register NTLM credentials for, e.g. /etc/pam.d/login,
-and modify as follows:
-
- ...
- auth substack system-auth
- +++ auth optional pam_cifscreds.so
- auth include postlogin
- ...
-
- ...
- session include system-auth
- +++ session optional pam_cifscreds.so domain=DOMAIN
- session include postlogin
- ...
-
-Change DOMAIN to the name of you Windows domain, or use host= as
-described below.
-
-=head1 DESCRIPTION
-
-The B<pam_cifscreds> PAM module is a tool for automatically adding
-credentials (username and password) for the purpose of establishing
-sessions in multiuser mounts.
-
-When a cifs filesystem is mounted with the "multiuser" option, and does
-not use krb5 authentication, it needs to be able to get the credentials
-for each user from somewhere. The B<pam_cifscreds> module can be used
-to provide these credentials to the kernel automatically at login.
-
-In the session section of the PAM configuration file, the module can
-either an NT domain name or a list of hostname or addresses.
-
-=head1 OPTIONS
-
-B<pam_cifscreds> supports a couple options which can be set in the PAM
-configuration files. You must have one (and only one) of domain= or
-host=.
-
-=over
-
-=item B<debug>
-
-Turns on some extra debug logging.
-
-=item B<domain>=<NT domain name>
-
-Credentials will be added for the specified NT domain name.
-
-=item B<host>=<hostname or IP address>[,...]
-
-Credentials will be added for the specified hostnames or IP addresses.
-
-=back
-
-=head1 NOTES
-
-The pam_cifscreds PAM module requires a kernel built with support for
-the B<login> key type. That key type was added in v3.3 in mainline Linux
-kernels.
-
-Since B<pam_cifscreds> adds keys to the session keyring, it is highly
-recommended that one use B<pam_keyinit> to ensure that a session keyring
-is established at login time.
-
-=head1 SEE ALSO
-
-cifscreds(1), pam_keyinit(8)
-
-=head1 AUTHOR
-
-The pam_cifscreds PAM module was developed by Orion Poplawski
-<orion@nwra.com>.
diff --git a/pam_cifscreds.rst b/pam_cifscreds.rst
new file mode 100644
index 0000000..8e8308c
--- /dev/null
+++ b/pam_cifscreds.rst
@@ -0,0 +1,116 @@
+=============
+pam_cifscreds
+=============
+
+-------------------------------------------------------
+PAM module to manage NTLM credentials in kernel keyring
+-------------------------------------------------------
+:Manual section: 8
+
+
+********
+SYNOPSIS
+********
+
+
+Edit the PAM configuration files for the systems that you want to
+automatically register NTLM credentials for, e.g. /etc/pam.d/login,
+and modify as follows:
+
+
+.. code-block:: perl
+
+ ...
+ auth substack system-auth
+ +++ auth optional pam_cifscreds.so
+ auth include postlogin
+ ...
+
+ ...
+ session include system-auth
+ +++ session optional pam_cifscreds.so domain=DOMAIN
+ session include postlogin
+ ...
+
+
+Change DOMAIN to the name of you Windows domain, or use host= as
+described below.
+
+
+***********
+DESCRIPTION
+***********
+
+
+The \ **pam_cifscreds**\ PAM module is a tool for automatically adding
+credentials (username and password) for the purpose of establishing
+sessions in multiuser mounts.
+
+When a cifs filesystem is mounted with the "multiuser" option, and does
+not use krb5 authentication, it needs to be able to get the credentials
+for each user from somewhere. The \ **pam_cifscreds**\ module can be used
+to provide these credentials to the kernel automatically at login.
+
+In the session section of the PAM configuration file, the module can
+either an NT domain name or a list of hostname or addresses.
+
+
+*******
+OPTIONS
+*******
+
+
+\ **pam_cifscreds**\ supports a couple options which can be set in the PAM
+configuration files. You must have one (and only one) of domain= or
+host=.
+
+
+\ **debug**\
+
+ Turns on some extra debug logging.
+
+
+
+\ **domain**\ =<NT domain name>
+
+ Credentials will be added for the specified NT domain name.
+
+
+
+\ **host**\ =<hostname or IP address>[,...]
+
+ Credentials will be added for the specified hostnames or IP addresses.
+
+
+
+
+*****
+NOTES
+*****
+
+
+The pam_cifscreds PAM module requires a kernel built with support for
+the \ **login**\ key type. That key type was added in v3.3 in mainline Linux
+kernels.
+
+Since \ **pam_cifscreds**\ adds keys to the session keyring, it is highly
+recommended that one use \ **pam_keyinit**\ to ensure that a session keyring
+is established at login time.
+
+
+********
+SEE ALSO
+********
+
+
+cifscreds(1), pam_keyinit(8)
+
+
+******
+AUTHOR
+******
+
+
+The pam_cifscreds PAM module was developed by Orion Poplawski
+<orion@nwra.com>.
+
diff --git a/setcifsacl.pod.in b/setcifsacl.pod.in
deleted file mode 100644
index e28b9e5..0000000
--- a/setcifsacl.pod.in
+++ /dev/null
@@ -1,117 +0,0 @@
-# turn into a manpage with the following command:
-#
-# pod2man -s 1 -u -c '' -r '' --stderr setcifsacl.pod setcifsacl.1
-#
-
-=head1 NAME
-
-setcifsacl - Userspace helper to alter an ACL in a security descriptor for Common Internet File System (CIFS)
-
-=head1 SYNOPSIS
-
-setcifsacl [-v|-a|-D|-M|-S] "{one or more ACEs}" {file system object}
-
-=head1 DESCRIPTION
-
-This tool is part of the cifs-utils suite.
-
-B<setcifsacl> is a userspace helper program for the Linux CIFS client
-file system. It is intended to alter an ACL of a security descriptor
-for a file system object. Whether a security descriptor to be set is
-applied or not is determined by the CIFS/SMB server.
-
-This program uses a plugin to handle the mapping of user and group
-names to SIDs. F<@pluginpath@> should be a symlink that points to the
-correct plugin to use.
-
-=head1 OPTIONS
-
-=over
-
-=item B<-h>
-
-Print usage message and exit.
-
-=item B<-v>
-
-Print version number and exit.
-
-=item B<-a>
-
-Add one or more ACEs to an ACL of a security descriptor. An ACE is
-added even if the same ACE exists in the ACL.
-
-=item B<-D>
-
-Delete one or more ACEs from an ACL of a security descriptor. Entire
-ACE has to match in an existing ACL for the listed ACEs to be deleted.
-
-=item B<-M>
-
-Modify one or more ACEs from an ACL of a security descriptor. SID and
-type are used to match for existing ACEs to be modified with the list
-of ACEs specified.
-
-=item B<-S>
-
-Set an ACL of security descriptor with the list of ACEs Existing ACL
-is replaced entirely with the specified ACEs.
-
-Every ACE entry starts with "ACL:" One or more ACEs are specified
-within double quotes. Multiple ACEs are separated by a comma.
-
-Following fields of an ACE can be modified with possible values:
-
-=over
-
-=item B<SID> - Either a name or a raw SID value.
-
-=item B<type> - ALLOWED (0x0), DENIED (0x1), OBJECT_ALLOWED (0x5),
-OBJECT_DENIED (0x6)
-
-=item B<flags> - OBJECT_INHERIT_FLAG (OI or 0x1),
-CONTAINER_INHERIT_FLAG (CI or 0x2), NO_PROPAGATE_INHERIT_FLAG (NI or
-0x4), INHERIT_ONLY_FLAG (IO or 0x8), INHERITED_ACE_FLAG (IA or 0x10)
-or a combination/OR of these values.
-
-=item B<mask> - Either one of FULL, CHANGE, READ, a combination of R W
-X D P O, or a hex value
-
-=back
-
-=back
-
-=head1 EXAMPLES
-
-=head2 Add an ACE
-
- setcifsacl -a "ACL:CIFSTESTDOM\user2:DENIED/0x1/D" <file_name>
- setcifsacl -a "ACL:CIFSTESTDOM\user1:ALLOWED/OI|CI|NI/D" <file_name>
-
-=head2 Delete an ACE
-
- setcifsacl -D "ACL:S-1-1-0:0x1/OI/0x1201ff" <file_name>
-
-=head2 Modify an ACE
-
- setcifsacl -M "ACL:CIFSTESTDOM\user1:ALLOWED/0x1f/CHANGE" <file_name>
-
-=head2 Set an ACL
-
- setcifsacl -S "ACL:CIFSTESTDOM\Administrator:0x0/0x0/FULL,ACL:CIFSTESTDOM\user2:0x0/0x0/FULL" <file_name>
-
-=head1 NOTES
-
-Kernel support for getcifsacl/setcifsacl utilities was initially
-introduced in the 2.6.37 kernel.
-
-=head1 SEE ALSO
-
-L<mount.cifs(8)>, L<getcifsacl(1)>
-
-=head1 AUTHOR
-
-Shirish Pargaonkar wrote the setcifsacl program.
-
-The Linux CIFS Mailing list is the preferred place to ask questions
-regarding these programs.
diff --git a/setcifsacl.rst.in b/setcifsacl.rst.in
new file mode 100644
index 0000000..ea981e2
--- /dev/null
+++ b/setcifsacl.rst.in
@@ -0,0 +1,185 @@
+==========
+setcifsacl
+==========
+
+------------------------------------------------------------------------------------------------
+Userspace helper to alter an ACL in a security descriptor for Common Internet File System (CIFS)
+------------------------------------------------------------------------------------------------
+:Manual section: 1
+
+
+********
+SYNOPSIS
+********
+
+
+setcifsacl [-v|-a|-D|-M|-S] "{one or more ACEs}" {file system object}
+
+
+***********
+DESCRIPTION
+***********
+
+
+This tool is part of the cifs-utils suite.
+
+\ **setcifsacl**\ is a userspace helper program for the Linux CIFS client
+file system. It is intended to alter an ACL of a security descriptor
+for a file system object. Whether a security descriptor to be set is
+applied or not is determined by the CIFS/SMB server.
+
+This program uses a plugin to handle the mapping of user and group
+names to SIDs. ``@pluginpath@`` should be a symlink that points to the
+correct plugin to use.
+
+
+*******
+OPTIONS
+*******
+
+
+
+\ **-h**\
+
+ Print usage message and exit.
+
+
+
+\ **-v**\
+
+ Print version number and exit.
+
+
+
+\ **-a**\
+
+ Add one or more ACEs to an ACL of a security descriptor. An ACE is
+ added even if the same ACE exists in the ACL.
+
+
+
+\ **-D**\
+
+ Delete one or more ACEs from an ACL of a security descriptor. Entire
+ ACE has to match in an existing ACL for the listed ACEs to be deleted.
+
+
+
+\ **-M**\
+
+ Modify one or more ACEs from an ACL of a security descriptor. SID and
+ type are used to match for existing ACEs to be modified with the list
+ of ACEs specified.
+
+
+
+\ **-S**\
+
+ Set an ACL of security descriptor with the list of ACEs Existing ACL
+ is replaced entirely with the specified ACEs.
+
+ Every ACE entry starts with "ACL:" One or more ACEs are specified
+ within double quotes. Multiple ACEs are separated by a comma.
+
+ Following fields of an ACE can be modified with possible values:
+
+
+ \ **SID**\ - Either a name or a raw SID value.
+
+
+
+ \ **type**\ - ALLOWED (0x0), DENIED (0x1), OBJECT_ALLOWED (0x5), OBJECT_DENIED (0x6)
+
+
+
+ \ **flags**\ - OBJECT_INHERIT_FLAG (OI or 0x1), CONTAINER_INHERIT_FLAG (CI or 0x2), NO_PROPAGATE_INHERIT_FLAG (NI or
+ 0x4), INHERIT_ONLY_FLAG (IO or 0x8), INHERITED_ACE_FLAG (IA or 0x10)
+ or a combination/OR of these values.
+
+
+
+ \ **mask**\ - Either one of FULL, CHANGE, READ, a combination of R W X D P O, or a hex value
+
+
+
+
+
+
+********
+EXAMPLES
+********
+
+
+Add an ACE
+==========
+
+
+
+.. code-block:: perl
+
+ setcifsacl -a "ACL:CIFSTESTDOM\user2:DENIED/0x1/D" <file_name>
+ setcifsacl -a "ACL:CIFSTESTDOM\user1:ALLOWED/OI|CI|NI/D" <file_name>
+
+
+
+Delete an ACE
+=============
+
+
+
+.. code-block:: perl
+
+ setcifsacl -D "ACL:S-1-1-0:0x1/OI/0x1201ff" <file_name>
+
+
+
+Modify an ACE
+=============
+
+
+
+.. code-block:: perl
+
+ setcifsacl -M "ACL:CIFSTESTDOM\user1:ALLOWED/0x1f/CHANGE" <file_name>
+
+
+
+Set an ACL
+==========
+
+
+
+.. code-block:: perl
+
+ setcifsacl -S "ACL:CIFSTESTDOM\Administrator:0x0/0x0/FULL,ACL:CIFSTESTDOM\user2:0x0/0x0/FULL" <file_name>
+
+
+
+
+*****
+NOTES
+*****
+
+
+Kernel support for getcifsacl/setcifsacl utilities was initially
+introduced in the 2.6.37 kernel.
+
+
+********
+SEE ALSO
+********
+
+
+mount.cifs(8), getcifsacl(1)
+
+
+******
+AUTHOR
+******
+
+
+Shirish Pargaonkar wrote the setcifsacl program.
+
+The Linux CIFS Mailing list is the preferred place to ask questions
+regarding these programs.
+