docs/howto/msdfs.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3                 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
   4   <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
   5   %global_entities;
   6 ]>
   7
   8 <chapter id="msdfs">
   9
  10 <chapterinfo>
  11         <author>
  12                 <firstname>Shirish</firstname><surname>Kalele</surname>
  13                 <affiliation>
  14                         <orgname>Samba Team &amp; Veritas Software</orgname>
  15                         <address>
  16                                 <email>samba@samba.org</email>
  17                         </address>
  18                 </affiliation>
  19         </author>
  20         &author.jht;
  21
  22         <pubdate>12 Jul 2000</pubdate>
  23 </chapterinfo>
  24
  25 <title>Hosting a Microsoft Distributed File System Tree</title>
  26
  27 <sect1>
  28 <title>Features and Benefits</title>
  29
  30         <para>
  31         The Distributed File System (DFS) provides a means of separating the logical
  32         view of files and directories that users see from the actual physical locations
  33         of these resources on the network. It allows for higher availability, smoother
  34         storage expansion, load balancing, and so on.
  35         </para>
  36
  37         <para>
  38         For information about DFS, refer to the
  39 <ulink url="http://www.microsoft.com/NTServer/nts/downloads/winfeatures/NTSDistrFile/AdminGuide.asp">Microsoft documentation</ulink>.
  40         This document explains how to host a DFS tree on a UNIX machine (for DFS-aware
  41         clients to browse) using Samba.
  42         </para>
  43
  44         <para>
  45         A Samba server can be made a DFS server by setting the global
  46         Boolean <smbconfoption><name>host msdfs</name></smbconfoption>
  47         parameter in the &smb.conf; file. You designate a share as a DFS
  48         root using the Share Level Boolean <smbconfoption><name>msdfs root</name></smbconfoption> parameter. A DFS root directory on Samba hosts DFS
  49         links in the form of symbolic links that point to other servers. For example, a symbolic link
  50         <filename>junction-&gt;msdfs:storage1\share1</filename> in the share directory acts
  51         as the DFS junction. When DFS-aware clients attempt to access the junction link,
  52         they are redirected to the storage location (in this case, <parameter>\\storage1\share1</parameter>).
  53         </para>
  54
  55         <para>
  56         DFS trees on Samba work with all DFS-aware clients ranging from Windows 95 to 200x.
  57         <link linkend="dfscfg">Following sample configuration</link> shows how to setup a DFS tree on a Samba server.
  58         In the <filename>/export/dfsroot</filename> directory, you set up your DFS links to
  59         other servers on the network.
  60 <screen>
  61 &rootprompt;<userinput>cd /export/dfsroot</userinput>
  62 &rootprompt;<userinput>chown root /export/dfsroot</userinput>
  63 &rootprompt;<userinput>chmod 755 /export/dfsroot</userinput>
  64 &rootprompt;<userinput>ln -s msdfs:storageA\\shareA linka</userinput>
  65 &rootprompt;<userinput>ln -s msdfs:serverB\\share,serverC\\share linkb</userinput>
  66 </screen>
  67 </para>
  68
  69 <para>
  70 <smbconfexample id="dfscfg">
  71 <title>smb.conf with DFS configured</title>
  72 <smbconfsection>[global]</smbconfsection>
  73 <smbconfoption><name>netbios name</name><value>&example.server.samba;</value></smbconfoption>
  74 <smbconfoption><name>host msdfs  </name><value>yes</value></smbconfoption>
  75
  76 <smbconfsection>[dfs]</smbconfsection>
  77 <smbconfoption><name>path</name><value>/export/dfsroot</value></smbconfoption>
  78 <smbconfoption><name>msdfs root</name><value>yes</value></smbconfoption>
  79 </smbconfexample>
  80 </para>
  81
  82         <para>You should set up the permissions and ownership of
  83         the directory acting as the DFS root so that only designated
  84         users can create, delete or modify the msdfs links. Also note
  85         that symlink names should be all lowercase. This limitation exists
  86         to have Samba avoid trying all the case combinations to get at
  87         the link name. Finally, set up the symbolic links to point to the
  88         network shares you want and start Samba.</para>
  89
  90         <para>Users on DFS-aware clients can now browse the DFS tree
  91         on the Samba server at \\samba\dfs. Accessing
  92         links linka or linkb (which appear as directories to the client)
  93         takes users directly to the appropriate shares on the network.</para>
  94 </sect1>
  95
  96 <sect1>
  97 <title>Common Errors</title>
  98         <itemizedlist>
  99                 <listitem><para>Windows clients need to be rebooted
 100                 if a previously mounted non-DFS share is made a DFS
 101                 root or vice versa. A better way is to introduce a
 102                 new share and make it the DFS root.</para>
 103                 </listitem>
 104
 105                 <listitem><para>Currently, there's a restriction that msdfs
 106                 symlink names should all be lowercase.</para>
 107                 </listitem>
 108
 109                 <listitem><para>For security purposes, the directory
 110                 acting as the root of the DFS tree should have ownership
 111                 and permissions set so only designated users can
 112                 modify the symbolic links in the directory.</para>
 113                 </listitem>
 114         </itemizedlist>
 115
 116         <sect2>
 117                 <title>MSDFS UNIX Path Is Case-Critical</title>
 118
 119                 <para>
 120                 A network administrator sent advice to the Samba mailing list
 121                 after a long sessions trying to determine why DFS was not working.
 122                 His advice is worth noting.
 123                 </para>
 124
 125                 <para><quote>
 126                 I spent some time trying to figure out why my particular
 127                 dfs root wasn't working. I noted in the documentation that
 128                 the symlink should be in all lowercase. It should be
 129                 amended that the entire path to the symlink should all be
 130                 in lowercase as well.
 131                 </quote></para>
 132
 133                 <para>
 134                 For example, I had a share defined as such:
 135
 136                 <screen>
 137                 [pub]
 138                         path = /export/home/Shares/public_share
 139                         msdfs root = yes
 140                 </screen>
 141
 142                 and I could not make my Windows 9x/Me (with the dfs client installed)
 143                 follow this symlink:
 144
 145                 <screen>
 146                         damage1 -> msdfs:damage\test-share
 147                 </screen>
 148                 </para>
 149
 150                 <para>
 151                 Running a debug level of 10 reveals:
 152
 153                 <programlisting>
 154                 [2003/08/20 11:40:33, 5] msdfs/msdfs.c:is_msdfs_link(176)
 155                   is_msdfs_link: /export/home/shares/public_share/* does not exist.
 156                 </programlisting>
 157
 158                 Curious. So I changed the directory name from .../Shares/... to
 159                 .../shares/... (along with my service definition) and it worked!
 160                 </para>
 161
 162         </sect2>
 163
 164 </sect1>
 165
 166 </chapter>