Convert ADS-HOWTO to SGML and add it to the howto collection

Updated generated docs
(This used to be commit 3d417179233d0b8e486560c41248888be42bacf9)

2 files changed, 197 insertions, 0 deletions

diff --git a/docs/docbook/projdoc/ADS-HOWTO.sgml b/docs/docbook/projdoc/ADS-HOWTO.sgml
new file mode 100644
index 0000000000..0d2fda5f78
--- /dev/null
+++ b/docs/docbook/projdoc/ADS-HOWTO.sgml
@@ -0,0 +1,195 @@
+<chapter id="ADS">
+
+<chapterinfo>
+	<author>
+		<firstname>Andrew</firstname><surname>Tridgell</surname>
+	</author>
+	<pubdate>2002</pubdate>
+</chapterinfo>
+
+<title>Using samba 3.0 with ActiveDirectory support</title>
+
+<para>
+This is a VERY ROUGH guide to setting up the current (November 2001)
+pre-alpha version of Samba 3.0 with kerberos authentication against a
+Windows2000 KDC. The procedures listed here are likely to change as
+the code develops.
+</para>
+
+<para>Pieces you need before you begin:
+<simplelist>
+<member>a Windows 2000 server.</member>
+<member>samba 3.0 or higher.</member>
+<member>the MIT kerberos development libraries (either install from the above sources or use a package). The heimdal libraries will not work.</member>
+<member>the OpenLDAP development libraries.</member>
+</simplelist>
+</para>
+
+<sect1>
+<title>Installing the required packages for Debian</title>
+
+<para>On Debian you need to install the following packages:
+<simplelist>
+<member>libkrb5-dev</member>
+<member>krb5-user</member>
+</simplelist>
+</para>
+</sect1>
+
+<sect1>
+<title>Installing the required packages for RedHat</title>
+
+<para>On RedHat this means you should have at least: 
+<simplelist>
+<member>krb5-workstation (for kinit)</member>
+<member>krb5-libs (for linking with)</member>
+<member>krb5-devel (because you are compiling from source)</member>
+</simplelist>
+</para>
+
+<para>in addition to the standard development environment.</para>
+
+<para>Note that these are not standard on a RedHat install, and you may need 
+to get them off CD2.</para>
+
+</sect1>
+
+<sect1>
+<title>Compile Samba</title>
+<para>If your kerberos libraries are in a non-standard location then
+  remember to add the configure option --with-krb5=DIR.</para>
+
+<para>After you run configure make sure that include/config.h contains 
+  lines like this:</para>
+
+<para><programlisting>
+#define HAVE_KRB5 1
+#define HAVE_LDAP 1
+</programlisting></para>
+
+<para>If it doesn't then configure did not find your krb5 libraries or
+  your ldap libraries. Look in config.log to figure out why and fix
+  it.</para>
+
+<para>Then compile and install Samba as usual. You must use at least the
+  following 3 options in smb.conf:</para>
+
+<para><programlisting>
+  realm = YOUR.KERBEROS.REALM
+  ads server = your.kerberos.server
+  security = ADS
+  encrypt passwords = yes
+</programlisting></para>
+
+<para>Strictly speaking, you can omit the realm name and you can use an IP
+  address for the ads server. In that case Samba will auto-detect these.</para>
+
+<para>You do *not* need a smbpasswd file, although it won't do any harm
+  and if you have one then Samba will be able to fall back to normal
+  password security for older clients. I expect that the above
+  required options will change soon when we get better active
+  directory integration.</para>
+</sect1>
+
+<sect1>
+<title>Setup your /etc/krb5.conf</title>
+
+<para>The minimal configuration for krb5.conf is:</para>
+
+<para><programlisting>
+	[realms]
+    YOUR.KERBEROS.REALM = {
+	kdc = your.kerberos.server
+    }
+</programlisting></para>
+
+<para>Test your config by doing a "kinit USERNAME@REALM" and making sure that
+  your password is accepted by the Win2000 KDC. </para>
+
+<para>NOTE: The realm must be uppercase. </para>
+
+<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 /etc/hosts
+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 step 5 now. Step 3 is only needed if you want kerberos
+support in smbd.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Create the computer account</title>
+
+<para>
+Do a "kinit" as a user that has authority to change arbitrary
+passwords on the KDC ("Administrator" is a good choice). Then as a
+user that has write permission on the Samba private directory
+(usually root) run:
+<command>net ads join</command>
+</para>
+
+<sect2>
+<title>Possible errors</title>
+
+<para>
+<variablelist>
+<varlistentry><term>"bash: kinit: command not found"</term>
+<listitem><para>kinit is in the krb5-workstation RPM on RedHat systems, and is in /usr/kerberos/bin, so it won't be in the path until you log in again (or open a new terminal)</para></listitem></varlistentry>
+<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>
+</variablelist>
+</para>
+
+</sect2>
+
+</sect1>
+
+<sect1>
+<title>Test your server setup</title>
+
+<para>
+On a Windows 2000 client try <command>net use * \\server\share</command>. You should
+be logged in with kerberos without needing to know a password. If
+this fails then run <command>klist tickets</command>. Did you get a ticket for the
+server? Does it have an encoding type of DES-CBC-MD5 ? 
+</para>
+
+</sect1>
+
+<sect1>
+<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 -k 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>
diff --git a/docs/docbook/projdoc/samba-doc.sgml b/docs/docbook/projdoc/samba-doc.sgml
index 75c5c379d3..6fb77750e7 100644
--- a/docs/docbook/projdoc/samba-doc.sgml
+++ b/docs/docbook/projdoc/samba-doc.sgml
@@ -21,6 +21,7 @@
 <!ENTITY GROUP-MAPPING-HOWTO SYSTEM "GROUP-MAPPING-HOWTO.sgml">
 <!ENTITY Portability SYSTEM "Portability.sgml">
 <!ENTITY Other-Clients SYSTEM "Other-Clients.sgml">
+<!ENTITY ADS-HOWTO SYSTEM "ADS-HOWTO.sgml">
 ]>
 
 <book id="Samba-Project-Documentation">
@@ -78,6 +79,7 @@ Cheers, jerry
 &Samba-PDC-HOWTO;
 &Samba-BDC-HOWTO;
 &Samba-LDAP;
+&ADS-HOWTO;
 &BROWSING;
 &SPEED;
 &Other-Clients;