Moving docs tree to docs-xml to make room for generated docs in the release tarball.

(This used to be commit 9f672c26d63955f613088489c6efbdc08b5b2d14)

1 files changed, 176 insertions, 0 deletions

diff --git a/docs-xml/Samba3-HOWTO/TOSHARG-msdfs.xml b/docs-xml/Samba3-HOWTO/TOSHARG-msdfs.xml
new file mode 100644
index 0000000000..528f41d8cb
--- /dev/null
+++ b/docs-xml/Samba3-HOWTO/TOSHARG-msdfs.xml
@@ -0,0 +1,176 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+<chapter id="msdfs">
+
+<chapterinfo>
+	<author>
+		<firstname>Shirish</firstname><surname>Kalele</surname>
+		<affiliation>
+			<orgname>Samba Team &amp; Veritas Software</orgname>
+			<address>
+				<email>samba@samba.org</email>
+			</address>
+		</affiliation>
+	</author>
+	&author.jht;
+	
+	<pubdate>12 Jul 2000</pubdate>
+</chapterinfo>
+
+<title>Hosting a Microsoft Distributed File System Tree</title>
+
+<sect1>
+<title>Features and Benefits</title>
+
+	<para>
+<indexterm><primary>distributed file system</primary><see>DFS</see></indexterm>
+<indexterm><primary>physical locations</primary></indexterm>
+<indexterm><primary>higher availability</primary></indexterm>
+<indexterm><primary>load balancing</primary></indexterm>
+<indexterm><primary>logical directories</primary></indexterm>
+	The distributed file system (DFS) provides a means of separating the logical
+	view of files and directories that users see from the actual physical locations
+	of these resources on the network. It allows for higher availability, smoother
+	storage expansion, load balancing, and so on.
+	</para>
+
+	<para>
+<indexterm><primary>DFS</primary></indexterm>
+<indexterm><primary>DFS tree</primary></indexterm>
+<indexterm><primary>DFS-aware</primary></indexterm>
+	For information about DFS, refer to the <ulink
+	url="http://www.microsoft.com/NTServer/nts/downloads/winfeatures/NTSDistrFile/AdminGuide.asp">Microsoft
+	documentation</ulink>.  This document explains how to host a DFS tree on a UNIX machine (for DFS-aware clients
+	to browse) using Samba.
+	</para>
+
+	<para>
+<indexterm><primary>DFS server</primary></indexterm>
+<indexterm><primary>share-level</primary></indexterm>
+<indexterm><primary>DFS junction</primary></indexterm>
+<indexterm><primary>DFS-aware</primary></indexterm>
+	A Samba server can be made a DFS server by setting the global Boolean <smbconfoption name="host msdfs"/>
+	parameter in the &smb.conf; file. You designate a share as a DFS root using the share-level Boolean
+	<smbconfoption name="msdfs root"/> parameter. A DFS root directory on Samba hosts DFS links in the form of
+	symbolic links that point to other servers. For example, a symbolic link
+	<filename>junction-&gt;msdfs:storage1\share1</filename> in the share directory acts as the DFS junction. When
+	DFS-aware clients attempt to access the junction link, they are redirected to the storage location (in this
+	case, <parameter>\\storage1\share1</parameter>).
+	</para>
+
+	<para>
+<indexterm><primary>DFS-aware</primary></indexterm>
+<indexterm><primary>DFS tree</primary></indexterm>
+<indexterm><primary>DFS links</primary></indexterm>
+<indexterm><primary>DFS</primary></indexterm>
+	DFS trees on Samba work with all DFS-aware clients ranging from Windows 95 to 200x.
+	<link linkend="dfscfg">The following sample configuration</link> shows how to setup a DFS tree on a Samba server.
+	In the <filename>/export/dfsroot</filename> directory, you set up your DFS links to 
+	other servers on the network.
+<screen>
+&rootprompt;<userinput>cd /export/dfsroot</userinput>
+&rootprompt;<userinput>chown root /export/dfsroot</userinput>
+&rootprompt;<userinput>chmod 755 /export/dfsroot</userinput>
+&rootprompt;<userinput>ln -s msdfs:storageA\\shareA linka</userinput>
+&rootprompt;<userinput>ln -s msdfs:serverB\\share,serverC\\share linkb</userinput>
+</screen>
+</para>
+
+<example id="dfscfg">
+<title>smb.conf with DFS Configured</title>
+<smbconfblock>
+<smbconfsection name="[global]"/>
+<smbconfoption name="netbios name">&example.server.samba;</smbconfoption>
+<smbconfoption name="host msdfs  ">yes</smbconfoption>
+
+<smbconfsection name="[dfs]"/>
+<smbconfoption name="path">/export/dfsroot</smbconfoption>
+<smbconfoption name="msdfs root">yes</smbconfoption>
+</smbconfblock>
+</example>
+
+	<para>
+<indexterm><primary>DFS root</primary></indexterm>
+<indexterm><primary>msdfs links</primary></indexterm>
+<indexterm><primary>symbolic links</primary></indexterm>
+	You should set up the permissions and ownership of the directory acting as the DFS root so that only
+	designated users can create, delete, or modify the msdfs links. Also note that symlink names should be all
+	lowercase. This limitation exists to have Samba avoid trying all the case combinations to get at the link
+	name. Finally, set up the symbolic links to point to the network shares you want and start Samba.
+	</para>
+
+	<para>
+<indexterm><primary>DFS-aware clients</primary></indexterm>
+<indexterm><primary>DFS tree</primary></indexterm>
+	Users on DFS-aware clients can now browse the DFS tree on the Samba server at
+	<constant>\\samba\dfs</constant>. Accessing links linka or linkb (which appear as directories to the client)
+	takes users directly to the appropriate shares on the network.
+	</para>
+
+</sect1>
+
+<sect1>
+<title>Common Errors</title>
+	<itemizedlist>
+		<listitem><para>Windows clients need to be rebooted 
+		if a previously mounted non-DFS share is made a DFS 
+		root, or vice versa. A better way is to introduce a 
+		new share and make it the DFS root.</para>
+		</listitem>
+		
+		<listitem><para>Currently, there's a restriction that msdfs 
+		symlink names should all be lowercase.</para>
+		</listitem>
+		
+		<listitem><para>For security purposes, the directory 
+		acting as the root of the DFS tree should have ownership 
+		and permissions set so only designated users can 
+		modify the symbolic links in the directory.</para>
+		</listitem>
+	</itemizedlist>
+
+	<sect2>
+		<title>MSDFS UNIX Path Is Case-Critical</title>
+
+		<para>
+		A network administrator sent advice to the Samba mailing list
+		after long sessions trying to determine why DFS was not working.
+		His advice is worth noting.
+		</para>
+
+		<para><quote>
+		I spent some time trying to figure out why my particular
+		DFS root wasn't working. I noted in the documentation that
+		the symlink should be in all lowercase. It should be
+		amended that the entire path to the symlink should all be
+		in lowercase as well.
+		</quote></para>
+
+		<para>
+		<quote>For example, I had a share defined as such:</quote>
+		<smbconfblock>
+		<smbconfsection name="[pub]"/>
+		<smbconfoption name="path">/export/home/Shares/public_share</smbconfoption>
+		<smbconfoption name="msdfs root">yes</smbconfoption>
+		</smbconfblock>
+		<quote>and I could not make my Windows 9x/Me (with the dfs client installed) follow this symlink:</quote>
+		<screen>
+		damage1 -> msdfs:damage\test-share
+		</screen>
+		</para>
+
+		<para>
+		<quote>Running a debug level of 10 reveals:</quote>
+		<programlisting>
+		[2003/08/20 11:40:33, 5] msdfs/msdfs.c:is_msdfs_link(176)
+		  is_msdfs_link: /export/home/shares/public_share/* does not exist.
+		</programlisting>
+		<quote>Curious. So I changed the directory name from <constant>.../Shares/...</constant> to
+		<constant>.../shares/...</constant> (along with my service definition) and it worked!</quote>
+		</para>
+
+	</sect2>
+
+</sect1>
+
+</chapter>