Adding missing files.

(This used to be commit 6b5e4a89bb668f78d2336d08830ceb6ffd79caef)

2 files changed, 467 insertions, 0 deletions

diff --git a/docs/Samba-HOWTO-Collection/TOSHARG-SecureLDAP.xml b/docs/Samba-HOWTO-Collection/TOSHARG-SecureLDAP.xml
new file mode 100644
index 0000000000..86e2845037
--- /dev/null
+++ b/docs/Samba-HOWTO-Collection/TOSHARG-SecureLDAP.xml
@@ -0,0 +1,406 @@
+<?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="ch-ldap-tls">
+    <title>Transport Layer Security</title>
+    <sect1 id="s1-intro-ldap-tls">
+      <title>Introduction</title>
+      <para>
+	<indexterm>
+	  <primary>Transport Layer Seccurity, TLS</primary>
+	  <secondary>Introduction</secondary>
+	</indexterm>
+	Up until now, we have discussed the straight forward configuration of
+	<trademark>OpenLDAP</trademark>, with some advanced features such as
+	<xref linkend="s1-acls"></xref>. This does not however, deal with the
+	fact that the network transmissions are still in plain text. This is
+	where <firstterm>Transport Layer Security (TLS)</firstterm> comes in.
+      </para>
+      <para>
+		  <trademark>OpenLDAP</trademark> clients and servers are capable of
+		  using the Transport Layer Security (TLS) framework to provide
+		  integrity and confidentiality protections in accordance with -
+		  <ulink url="http://rfc.net/rfc2830.html">RFC2830</ulink>;
+		  <emphasis>Lightweight Directory Access Protocol (v3): Extension
+			  for Transport Layer Security</emphasis>
+      </para>
+      <para>
+		  TLS uses X.509 certificates. All servers are required to have valid
+		  certificates, whereas client certificates are optional. We will only
+		  be discussing server certificates.
+	<tip>
+	  <para>
+		  The DN of a server certificate must use the CN attribute to name the
+		  server, and the CN must carry the server's fully qualified domain name
+		  (FQDN). Additional alias names and wildcards may be present in the
+		  <option>subjectAltName</option> certificate extension. More details on
+		  server certificate names are in
+		  <ulink url="http://rfc.net/rfc2830.html">RFC2830</ulink>.
+	  </para>
+	</tip>
+      </para>
+      <para>
+	We will discuss this more in the next sections.
+      </para>
+    </sect1>
+
+    <sect1 id="s1-config-ldap-tls">
+      <title>Configuring</title>
+      <para>
+	<indexterm>
+	  <primary>Transport Layer Seccurity, TLS</primary>
+	  <secondary>Configuring</secondary>
+	</indexterm>
+	Now on to the good bit.
+      </para>
+      
+      <sect2 id="s1-config-ldap-tls-certs">
+	<title>Generating the Certificate Authority</title>
+      <para>
+		  In order to create the relevant certificates, we need to become our own
+		  Certificate Authority (CA).
+	<footnote>
+	  <para>
+		  We could however, get our generated server certificate signed by proper CAs,
+		  like <ulink url="http://www.thawte.com/">Thawte</ulink> and
+		  <ulink url="http://www.verisign.com/">VeriSign</ulink>, which you pay for,
+		  or the free ones, via <ulink url="http://www.cacert.org/">CAcert</ulink>
+	  </para>
+	</footnote>
+	 This is necessary, so we can sign the server certificate.
+      </para>
+      <para>
+	We will be using the <ulink url="http://www.openssl.org">OpenSSL</ulink>
+	<footnote>
+	  <para>
+		  The downside to making our own CA, is that the certificate is not automatically
+		  recognised by clients, like the commercial ones are.
+	  </para>
+	</footnote>
+	software for this, which is included with every great
+	<trademark class="registered">Linux</trademark> distribution.
+      </para>
+      <para>
+	TLS is used for many types of servers, but the instructions
+	<footnote>
+	  <para>
+		  For information straight from the horses mouth, please visit -
+		  <ulink url="http://www.openssl.org/docs/HOWTO/">
+			  ttp://www.openssl.org/docs/HOWTO/</ulink>; the main OpenSSL site.     
+	  </para>
+	</footnote>
+	presented here, are tailored for &OL;.
+	<note>
+	  <para>
+		  The <emphasis>Common Name (CN)</emphasis>, if the following example,
+		  <emphasis>MUST</emphasis> be the fully qualified domain name (fqdn)
+		  of your ldap server.
+	  </para>
+	</note>
+	  </para>
+	<para>
+	  First we need to generate the CA:
+	  <screen width="90">
+	    <computeroutput>
+[ghenry@suretec ldap-docs]$ mkdir myCA
+	    </computeroutput>
+	  </screen>
+	  Move into that directory:
+	  <screen width="90">
+	    <computeroutput>
+[ghenry@suretec ldap-docs]$ cd myCA
+	    </computeroutput>
+	  </screen>
+	  Now generate the CA:
+	  <footnote>
+	    <para>
+			Your <filename>CA.pl</filename> or <filename>CA.sh</filename> might
+			not be in the same location as mine is, you can find it by using the
+			<command>locate</command> command, i.e. <command>locate CA.pl</command>.
+			If the command complains about the database being too old, run
+			<command>updatedb</command> as <emphasis>root</emphasis> to update it.
+	    </para>
+	  </footnote>
+	  <screen width="90">
+	    <computeroutput>
+[ghenry@suretec myCA]$ /usr/share/ssl/misc/CA.pl -newca
+CA certificate filename (or enter to create)
+	      
+Making CA certificate ...
+Generating a 1024 bit RSA private key
+.......................++++++
+.............................++++++
+writing new private key to './demoCA/private/cakey.pem'
+Enter PEM pass phrase:
+Verifying - Enter PEM pass phrase:
+-----
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:GB
+State or Province Name (full name) [Some-State]:Aberdeenshire
+Locality Name (eg, city) []:Aberdeen
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:Suretec Systems Ltd.
+Organizational Unit Name (eg, section) []:IT
+Common Name (eg, YOUR name) []:ldap.suretecsystems.com
+Email Address []:support@suretecsystems.com
+	    </computeroutput>
+	  </screen>
+	</para>
+	<para>
+	  Now, there are some things to note here. 
+	  <orderedlist>
+	    <listitem>
+	      <para>
+			  You <emphasis>MUST</emphasis> remember the password, as we will need
+			  it to sign the server certificate..
+	      </para>
+	    </listitem>
+	    <listitem>
+	      <para>
+			  The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be the
+			  fully qualified domain name (fqdn) of your ldap server.
+	      </para>
+	    </listitem>
+	  </orderedlist>
+	</para>
+      </sect2>
+
+      <sect2 id="s1-config-ldap-tls-server">
+	<title>Generating the Server Certificate</title>
+	<para>
+	  Now we need to generate the server certificate:
+	  <screen width="90">
+	    <computeroutput>
+[ghenry@suretec myCA]$ openssl req -new -nodes -keyout newreq.pem -out newreq.pem
+Generating a 1024 bit RSA private key
+.............++++++
+........................................................++++++
+writing new private key to 'newreq.pem'
+-----
+You are about to be asked to enter information that will be incorporated
+into your certificate request.
+What you are about to enter is what is called a Distinguished Name or a DN.
+There are quite a few fields but you can leave some blank
+For some fields there will be a default value,
+If you enter '.', the field will be left blank.
+-----
+Country Name (2 letter code) [AU]:GB
+State or Province Name (full name) [Some-State]:Aberdeenshire
+Locality Name (eg, city) []:Aberdeen
+Organization Name (eg, company) [Internet Widgits Pty Ltd]:Suretec Systems Ltd.
+Organizational Unit Name (eg, section) []:IT
+Common Name (eg, YOUR name) []:ldap.suretecsystems.com
+Email Address []:support@suretecsystems.com
+	      
+Please enter the following 'extra' attributes
+to be sent with your certificate request
+A challenge password []:
+An optional company name []:
+	    </computeroutput>
+	  </screen>
+	</para>	
+	<para>
+	  Again, there are some things to note here. 
+	  <orderedlist>
+	    <listitem>
+	      <para>
+		You should <emphasis>NOT</emphasis> enter a password.
+	      </para>
+	    </listitem>
+	    <listitem>
+	      <para>
+			  The <emphasis>Common Name (CN)</emphasis>, <emphasis>MUST</emphasis> be
+			  the fully qualified domain name (fqdn) of your ldap server.
+	      </para>
+	    </listitem>
+	  </orderedlist>
+	</para>		
+	<para>
+	  Now, we sign the certificate with the new CA:
+	  <screen width="90">
+	    <computeroutput>
+[ghenry@suretec myCA]$ /usr/share/ssl/misc/CA.pl -sign
+Using configuration from /etc/ssl/openssl.cnf
+Enter pass phrase for ./demoCA/private/cakey.pem:
+Check that the request matches the signature
+Signature ok
+Certificate Details:
+        Serial Number: 1 (0x1)
+        Validity
+            Not Before: Mar  6 18:22:26 2005 GMT
+            Not After : Mar  6 18:22:26 2006 GMT
+        Subject:
+            countryName               = GB
+            stateOrProvinceName       = Aberdeenshire
+            localityName              = Aberdeen
+            organizationName          = Suretec Systems Ltd.
+            organizationalUnitName    = IT
+            commonName                = ldap.suretecsystems.com
+            emailAddress              = support@suretecsystems.com
+        X509v3 extensions:
+            X509v3 Basic Constraints:
+                CA:FALSE
+            Netscape Comment:
+                OpenSSL Generated Certificate
+            X509v3 Subject Key Identifier:
+                F7:84:87:25:C4:E8:46:6D:0F:47:27:91:F0:16:E0:86:6A:EE:A3:CE
+            X509v3 Authority Key Identifier:
+                keyid:27:44:63:3A:CB:09:DC:B1:FF:32:CC:93:23:A4:F1:B4:D5:F0:7E:CC
+                DirName:/C=GB/ST=Aberdeenshire/L=Aberdeen/O=Suretec Systems Ltd./OU=IT/CN=ldap.suretecsystems.com/emailAddress=support@suretecsystems.com
+                serial:00
+
+Certificate is to be certified until Mar  6 18:22:26 2006 GMT (365 days)
+Sign the certificate? [y/n]:y
+
+
+1 out of 1 certificate requests certified, commit? [y/n]y
+Write out database with 1 new entries
+Data Base Updated
+Signed certificate is in newcert.pem
+	    </computeroutput>
+	  </screen>
+	</para>
+	<para>
+	  That completes the server certificate generation. 
+	</para>
+      </sect2>
+      <sect2 id="s1-config-ldap-tls-install">
+	<title>Installing the Certificates</title>
+	<para>
+		Now we need to copy the certificates to the right configuration directories,
+		rename them at the same time for convenience, change the ownership and
+		finally the permissions:
+	  <screen width="90">
+	    <computeroutput>
+[ghenry@suretec myCA]$ cp demoCA/cacert.pem /etc/openldap/
+[ghenry@suretec myCA]$ cp newcert.pem /etc/openldap/servercrt.pem
+[ghenry@suretec myCA]$ cp newreq.pem /etc/openldap/serverkey.pem
+[ghenry@suretec myCA]$ chown ldap.ldap /etc/openldap/*.pem
+[ghenry@suretec myCA]$ chmod 640 /etc/openldap/cacert.pem; chmod 600 /etc/openldap/serverkey.pem
+	    </computeroutput>
+	  </screen>
+	</para>
+	<para>
+		Now we just need to add these locations to <filename>slapd.conf</filename>,
+		anywhere before the <option>database</option> declaration and <filename>ldap.conf</filename>:
+	</para>
+	<para>
+	  <filename>slapd.conf</filename>
+	  <screen width="90">
+	    <computeroutput>
+TLSCertificateFile /etc/openldap/servercrt.pem
+TLSCertificateKeyFile /etc/openldap/serverkey.pem
+TLSCACertificateFile /etc/openldap/cacert.pem
+	    </computeroutput>
+	  </screen>
+	</para>
+	<para>
+	  <filename>ldap.conf</filename>
+	  <screen width="90">
+	    <computeroutput>
+TLS_CACERT /etc/openldap/cacert.pem
+	    </computeroutput>
+	  </screen>
+	</para>
+	<para>
+	  That's all there is to it. Now on to <xref linkend="s1-test-ldap-tls"></xref>
+	</para>
+      </sect2>
+    </sect1>
+
+    <sect1 id="s1-test-ldap-tls">
+      <title>Testing</title>
+      <para>
+	<indexterm>
+	  <primary>Transport Layer Seccurity, TLS</primary>
+	  <secondary>Testing</secondary>
+	</indexterm>
+	This is the easy part. Restart the server:
+	<screen width="90">
+	  <computeroutput>
+[ghenry@suretec myCA]$ /etc/init.d/ldap restart
+Stopping slapd:                                            [  OK  ]
+Checking configuration files for slapd: config file testing succeeded
+Starting slapd:                                            [  OK  ]
+	  </computeroutput>
+	</screen>
+	Then, using <command>ldapsearch</command>, test an anonymous search with the <option>-ZZ</option> 
+	<footnote>
+	  <para>
+	    See <command>man ldapsearch</command>:
+	  </para>
+	</footnote>
+	option:
+	<screen width="90">
+	  <computeroutput>
+[ghenry@suretec myCA]$ ldapsearch -x -b "dc=ldap,dc=suretecsystems,dc=com" -H 'ldap://ldap.suretecsystems.com:389' -ZZ
+	  </computeroutput>
+	</screen>
+	Your results should be the same as before you restarted the server, for example:
+	<screen width="90">
+	  <computeroutput>
+[ghenry@suretec myCA]$ ldapsearch -x -b "dc=ldap,dc=suretecsystems,dc=com" -H 'ldap://ldap.suretecsystems.com:389' -ZZ
+
+# extended LDIF
+#
+# LDAPv3
+# base &lt;&gt; with scope sub
+# filter: (objectclass=*)
+# requesting: ALL
+#
+
+# suretecsystems.com
+dn: dc=ldap,dc=suretecsystems,dc=com
+objectClass: dcObject
+objectClass: organization
+o: Suretec Systems Ltd.
+dc: suretecsystems
+
+# Manager, ldap.suretecsystems.com
+dn: cn=Manager,dc=ldap,dc=suretecsystems,dc=com
+objectClass: organizationalRole
+cn: Manager
+
+# SURETEC, suretecsystems.com
+dn: sambaDomainName=SURETEC,dc=ldap,dc=suretecsystems,dc=com
+sambaDomainName: SURETEC
+sambaSID: S-1-5-21-238355452-1056757430-1592208922
+sambaAlgorithmicRidBase: 1000
+objectClass: sambaDomain
+sambaNextUserRid: 67109862
+sambaNextGroupRid: 67109863
+	  </computeroutput>
+	</screen>
+	If you have any problems, please read <xref linkend="s1-int-ldap-tls"></xref>
+      </para>
+    </sect1>
+
+    <sect1 id="s1-int-ldap-tls">
+      <title>Troubleshooting</title>
+      <para>
+	<indexterm>
+	  <primary>Transport Layer Seccurity, TLS</primary>
+	  <secondary>Troubleshooting</secondary>
+	</indexterm>
+	The most common error when configuring TLS, as I have already mentioned
+	numerous times, is that the <emphasis>Common Name (CN)</emphasis> you entered
+	in <xref linkend="s1-config-ldap-tls-server"></xref> is <emphasis>NOT</emphasis>
+	the Full Qualified Domain Name (FQDN) of your ldap server.
+      </para>
+	  <para>Other errors could be that you have a typo somewhere in your
+		  <command>ldapsearch</command> command, or that your have the wrong
+		  permissions on the <filename>servercrt.pem</filename> and
+		  <filename>cacert.pem</filename> files. They should be set with
+		  <command>chmod 640</command>, as per <xref linkend="s1-config-ldap-tls-install"></xref>.
+      </para>
+      <para>
+		  For anything else, it's best to read through your ldap logfile or
+		  join the &OL; mailing list.
+      </para>
+    </sect1>
+
+</chapter>
diff --git a/docs/Samba-HOWTO-Collection/TOSHARG-preface.xml b/docs/Samba-HOWTO-Collection/TOSHARG-preface.xml
new file mode 100644
index 0000000000..43df53e523
--- /dev/null
+++ b/docs/Samba-HOWTO-Collection/TOSHARG-preface.xml
@@ -0,0 +1,61 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!DOCTYPE book PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
+
+<preface id="TOSHpreface">
+<title>Preface</title>
+
+<para>
+The editors wish to thank you for your decision to purchase this book.
+The Official Samba-3 HOWTO and Reference Guide is the result of many years
+of accumulation of information, feedback, tips, hints, and happy solutions.
+</para>
+
+<para>
+Please note that this book is a living document, the contents of which are
+constantly being updated. We encourage you to contribute your tips, techniques,
+helpful hints, and your special insight into the Windows networking world to
+help make the next generation of this book even more valuable to Samba users.
+</para>
+
+<para>
+We have made a concerted effort to document more comprehensively than has been
+done previously the information that may help you to better deploy Samba and to
+gain more contented network users.
+</para>
+
+<para>
+This book provides example configurations, it documents key aspects of Microsoft
+Windows networking, provides in-depth insight into the important configuration of
+Samba-3, and helps to put all of these into a useful framework.
+</para>
+
+<para>
+The most recent electronic versions of this document can be found at
+<ulink noescape="1" url="http://www.samba.org/">http://www.samba.org/</ulink>
+on the <quote>Documentation</quote> page.
+</para>
+
+<para>
+Updates, patches and corrections are most welcome. Please email your contributions
+to any one of the following:
+</para>
+
+<para>
+<simplelist>
+<member><ulink noescape="1" url="mailto:jelmer@samba.org">Jelmer Vernooij (jelmer@samba.org)</ulink></member>
+<member><ulink noescape="1" url="mailto:jht@samba.org">John H. Terpstra (jht@samba.org)</ulink></member>
+<member><ulink noescape="1" url="mailto:jerry@samba.org">Gerald (Jerry) Carter (jerry@samba.org)</ulink></member>
+</simplelist>
+</para>
+
+<para>
+We wish to advise that only original and unencumbered material can be published. Please do not submit
+content that is not your own work unless proof of consent from the copyright holder accompanies your
+submission.
+</para>
+
+  <!-- the conventions used in this book -->
+  <xi:include href="conventions.xml" xmlns:xi="http://www.w3.org/2003/XInclude" />
+
+
+</preface>