docs-xml: Add a vfs_widelinks manpage.

Signed-off-by: Jeremy Allison <jra@samba.org>
Reviewed-by: Ralph Boehme <slow@samba.org>

2 files changed, 91 insertions, 0 deletions

diff --git a/docs-xml/manpages/vfs_widelinks.8.xml b/docs-xml/manpages/vfs_widelinks.8.xml
new file mode 100644
index 00000000000..b8973701d23
--- /dev/null
+++ b/docs-xml/manpages/vfs_widelinks.8.xml
@@ -0,0 +1,90 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<refentry id="vfs_widelinks.8">
+
+<refmeta>
+	<refentrytitle>vfs_widelinks</refentrytitle>
+	<manvolnum>8</manvolnum>
+	<refmiscinfo class="source">Samba</refmiscinfo>
+	<refmiscinfo class="manual">System Administration tools</refmiscinfo>
+	<refmiscinfo class="version">&doc.version;</refmiscinfo>
+</refmeta>
+
+
+<refnamediv>
+	<refname>vfs_widelinks</refname>
+	<refpurpose>make a Samba share ignore filesystem symbolic links inside a share</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+	<cmdsynopsis>
+		<command>vfs objects = widelinks</command>
+	</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+	<title>DESCRIPTION</title>
+
+	<para>This VFS module is part of the
+	<citerefentry><refentrytitle>samba</refentrytitle>
+	<manvolnum>7</manvolnum></citerefentry> suite.</para>
+
+	<para>The <command>vfs_widelinks</command> VFS module
+	hides the existence of symbolic links in the filesystem
+	inside a share. It is used in Samba verson 4.13 and above
+	to implement the <filename>smb.conf</filename>"wide links = yes"
+	functionality that used to be inside the core smbd code.
+	The module should not be loaded explicitly by smb.conf
+	as part of the "vfs objects =" parameter, but is loaded
+	implicitly when "wide links = yes" is enabled. This is
+	to prevent existing smb.conf files from having to be
+	modified to keep the existing insecure "wide links"
+	functionality on a share.
+	</para>
+	<para>Please note that "wide links = yes" functionality
+	is a deliberately insecure option, and should never be
+	used in Samba installations. On Linux, bind mounts can
+	be used instead to implement anything "wide links = yes"
+	can enable. This module has been created to provide
+	backwards compatibility with existing users of
+	"wide links = yes" installations, but this use cannot be
+	recommended and is not endorsed by the Samba developers.
+	</para>
+	<para>Note that this implicit loading may become explicit
+	in a later Samba release, and administrators wishing to
+	keep the insecure "wide links" functionality may have
+	to add this module into their "vfs objects =" module
+	list. The Samba project release notes and this manpage
+	will be updated to reflect this when this change is made.
+	</para>
+
+	<para>This module is stackable.</para>
+
+</refsect1>
+
+<refsect1>
+	<title>EXAMPLES</title>
+
+	<para>No examples listed. This module is implicitly loaded
+	by smbd as needed.
+	</para>
+</refsect1>
+
+<refsect1>
+	<title>VERSION</title>
+
+	<para>This man page is part of version &doc.version; of the Samba suite.
+	</para>
+</refsect1>
+
+<refsect1>
+	<title>AUTHOR</title>
+
+	<para>The original Samba software and related utilities
+	were created by Andrew Tridgell. Samba is now developed
+	by the Samba Team as an Open Source project similar
+	to the way the Linux kernel is developed.</para>
+
+</refsect1>
+
+</refentry>
diff --git a/docs-xml/wscript_build b/docs-xml/wscript_build
index 21158e11fe7..9f87e86272b 100644
--- a/docs-xml/wscript_build
+++ b/docs-xml/wscript_build
@@ -108,6 +108,7 @@ vfs_module_manpages = ['vfs_acl_tdb',
                        'vfs_tsmsm',
                        'vfs_unityed_media',
                        'vfs_virusfilter',
+                       'vfs_widelinks',
                        'vfs_worm',
                        'vfs_xattr_tdb',
                        'vfs_zfsacl' ]