Docbook XML conversion: projdoc

(This used to be commit f7c9df751459da2d4a996d5f0135334fb3f87f69)

1 files changed, 167 insertions, 0 deletions

diff --git a/docs/docbook/projdoc/ADS-HOWTO.xml b/docs/docbook/projdoc/ADS-HOWTO.xml
new file mode 100644
index 0000000000..c89a0e4f87
--- /dev/null
+++ b/docs/docbook/projdoc/ADS-HOWTO.xml
@@ -0,0 +1,167 @@
+<chapter id="ADS">
+
+<chapterinfo>
+	&author.tridge;
+	&author.jelmer;
+	<pubdate>2002/2003</pubdate>
+</chapterinfo>
+
+<title>Samba as a ADS domain member</title>
+
+<para>
+This is a rough guide to setting up Samba 3.0 with kerberos authentication against a
+Windows2000 KDC. 
+</para> 
+
+<sect1>
+<title>Setup your <filename>smb.conf</filename></title>
+
+<para>You must use at least the following 3 options in smb.conf:</para>
+
+<para><programlisting>
+	realm = YOUR.KERBEROS.REALM
+	security = ADS
+	encrypt passwords = yes
+</programlisting></para>
+
+<para>
+In case samba can't figure out your ads server using your realm name, use the 
+<command>ads server</command> option in <filename>smb.conf</filename>:
+<programlisting>
+	ads server = your.kerberos.server
+</programlisting>
+</para>
+
+<note><para>You do *not* need a smbpasswd file, and older clients will
+  be authenticated as if <command>security = domain</command>,
+  although it won't do any harm
+  and allows you to have local users not in the domain.
+  I expect that the above required options will change soon when we get better
+  active directory integration.</para></note>
+
+</sect1>
+  
+<sect1>
+<title>Setup your <filename>/etc/krb5.conf</filename></title>
+
+<para>Note: you will need the krb5 workstation, devel, and libs installed</para>
+
+<para>The minimal configuration for <filename>krb5.conf</filename> is:</para>
+
+<para><programlisting>
+	[realms]
+	    YOUR.KERBEROS.REALM = {
+		kdc = your.kerberos.server
+	    }
+</programlisting></para>
+
+<para>Test your config by doing a <userinput>kinit
+<replaceable>USERNAME</replaceable>@<replaceable>REALM</replaceable></userinput> and
+making sure that your password is accepted by the Win2000 KDC.
+</para>
+
+<note><para>The realm must be uppercase or you will get "Cannot find KDC for requested
+realm while getting initial credentials" error </para></note>
+
+<note><para>Time between the two servers must be synchronized.  You will get a
+"kinit(v5): Clock skew too great while getting initial credentials" if the time
+difference is more than five minutes. </para></note>
+
+<para>
+You also must ensure that you can do a reverse DNS lookup on the IP
+address of your KDC. Also, the name that this reverse lookup maps to
+must either be the netbios name of the KDC (ie. the hostname with no
+domain attached) or it can alternatively be the netbios name
+followed by the realm. 
+</para>
+
+<para>
+The easiest way to ensure you get this right is to add a 
+<filename>/etc/hosts</filename> entry mapping the IP address of your KDC to 
+its netbios name. If you don't get this right then you will get a 
+"local error" when you try to join the realm.
+</para>
+
+<para>
+If all you want is kerberos support in &smbclient; then you can skip
+straight to <link linkend="ads-test-smbclient">Test with &smbclient;</link> now. 
+<link linkend="ads-create-machine-account">Creating a computer account</link> 
+and <link linkend="ads-test-server">testing your servers</link>
+is only needed if you want kerberos support for &smbd; and &winbindd;.
+</para>
+
+</sect1>
+
+<sect1 id="ads-create-machine-account">
+<title>Create the computer account</title>
+
+<para>
+As a user that has write permission on the Samba private directory
+(usually root) run:
+<programlisting>
+	<userinput>net join -U Administrator%password</userinput>
+</programlisting>
+</para>
+
+<sect2>
+<title>Possible errors</title>
+
+<para>
+<variablelist>
+	<varlistentry><term>"ADS support not compiled in"</term>
+	<listitem><para>Samba must be reconfigured (remove config.cache) and recompiled
+	(make clean all install) after the kerberos libs and headers are installed.
+	</para></listitem></varlistentry>
+
+	<varlistentry><term>net join prompts for user name</term>
+	<listitem><para>You need to login to the domain using <userinput>kinit
+	<replaceable>USERNAME</replaceable>@<replaceable>REALM</replaceable></userinput>.
+	<replaceable>USERNAME</replaceable> must be a user who has rights to add a machine
+	to the domain.  </para></listitem></varlistentry>
+</variablelist>
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1 id="ads-test-server">
+<title>Test your server setup</title>
+
+<para>
+If the join was successful, you will see a new computer account with the
+NetBIOS name of your Samba server in Active Directory (in the "Computers"
+folder under Users and Computers.
+</para>
+
+<para>
+On a Windows 2000 client try <userinput>net use * \\server\share</userinput>. You should
+be logged in with kerberos without needing to know a password. If
+this fails then run <userinput>klist tickets</userinput>. Did you get a ticket for the
+server? Does it have an encoding type of DES-CBC-MD5 ? 
+</para>
+
+</sect1>
+
+<sect1 id="ads-test-smbclient">
+<title>Testing with &smbclient;</title>
+
+<para>
+On your Samba server try to login to a Win2000 server or your Samba
+server using &smbclient; and kerberos. Use &smbclient; as usual, but
+specify the <parameter>-k</parameter> option to choose kerberos authentication.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Notes</title>
+
+<para>You must change administrator password at least once after DC 
+install, to create the right encoding types</para>
+
+<para>w2k doesn't seem to create the _kerberos._udp and _ldap._tcp in
+   their defaults DNS setup. Maybe fixed in service packs?</para>
+</sect1>
+
+</chapter>