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

(This used to be commit 9f672c26d63955f613088489c6efbdc08b5b2d14)

14 files changed, 400 insertions, 0 deletions

diff --git a/docs-xml/smbdotconf/ldap/clientldapsaslwrapping.xml b/docs-xml/smbdotconf/ldap/clientldapsaslwrapping.xml
new file mode 100644
index 0000000000..a926cec645
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/clientldapsaslwrapping.xml
@@ -0,0 +1,44 @@
+<samba:parameter name="client ldap sasl wrapping"
+                 context="G"
+               	 type="string"
+		 advanced="1" 
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+	<para>
+	The <smbconfoption name="client ldap sasl wrapping"/> defines whether
+	ldap traffic will be signed or signed and encrypted (sealed). 
+	Possible values are <emphasis>plain</emphasis>, <emphasis>sign</emphasis> 
+	and <emphasis>seal</emphasis>. 	
+	</para>
+
+	<para>
+	The values <emphasis>sign</emphasis> and <emphasis>seal</emphasis> are 
+	only available if Samba has been compiled against a modern 
+	OpenLDAP version (2.3.x or higher).
+	</para>
+	
+	<para>
+	This option is needed in the case of Domain Controllers enforcing 
+	the usage of signed LDAP connections (e.g. Windows 2000 SP3 or higher).
+	LDAP sign and seal can be controlled with the registry key
+	"<literal>HKLM\System\CurrentControlSet\Services\</literal>
+	<literal>NTDS\Parameters\LDAPServerIntegrity</literal>"
+	on the Windows server side.  
+	</para>
+
+	<para>
+	Depending on the used KRB5 library (MIT and older Heimdal versions)
+	it is possible that the message "integrity only" is not supported. 
+	In this case, <emphasis>sign</emphasis> is just an alias for 
+	<emphasis>seal</emphasis>.
+	</para>
+
+	<para>
+	The default value is <emphasis>plain</emphasis> which is not irritable 
+	to KRB5 clock skew errors. That implies synchronizing the time
+	with the KDC in the case of using <emphasis>sign</emphasis> or 
+	<emphasis>seal</emphasis>.
+	</para>
+</description>
+<value type="default">plain</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapadmindn.xml b/docs-xml/smbdotconf/ldap/ldapadmindn.xml
new file mode 100644
index 0000000000..442d242679
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapadmindn.xml
@@ -0,0 +1,21 @@
+<samba:parameter name="ldap admin dn"
+                 context="G"
+                 advanced="1" developer="1"
+				 type="string"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+				 <description>
+
+	 <para>
+	The <smbconfoption name="ldap admin dn"/> defines the Distinguished  Name (DN) name used by Samba to contact
+	the ldap server when retreiving  user account information. The <smbconfoption name="ldap admin dn"/> is used
+	in conjunction with the admin dn password stored in the <filename moreinfo="none">private/secrets.tdb</filename>
+	file.  See the <citerefentry><refentrytitle>smbpasswd</refentrytitle> <manvolnum>8</manvolnum></citerefentry>
+	man page for more information on how  to accomplish this.
+	</para>
+
+	<para>
+	The <smbconfoption name="ldap admin dn"/> requires a fully specified DN. The <smbconfoption name="ldap
+	suffix"/> is not appended to the <smbconfoption name="ldap admin dn"/>.
+	</para>
+</description>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapdeletedn.xml b/docs-xml/smbdotconf/ldap/ldapdeletedn.xml
new file mode 100644
index 0000000000..48f5c9b65a
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapdeletedn.xml
@@ -0,0 +1,14 @@
+<samba:parameter name="ldap delete dn"
+                 context="G"
+				 type="boolean"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+	<para> This parameter specifies whether a delete
+	operation in the ldapsam deletes the complete entry or only the attributes
+	specific to Samba.
+	</para>
+</description>
+
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapgroupsuffix.xml b/docs-xml/smbdotconf/ldap/ldapgroupsuffix.xml
new file mode 100644
index 0000000000..8fe033a2f9
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapgroupsuffix.xml
@@ -0,0 +1,16 @@
+<samba:parameter name="ldap group suffix"
+                 context="G"
+				 type="string"
+		 advanced="1" developer="1"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+	<para>This parameter specifies the suffix that is 
+	used for groups when these are added to the LDAP directory.
+	If this parameter is unset, the value of <smbconfoption 
+	name="ldap suffix"/> will be used instead.  The suffix string is pre-pended to the
+        <smbconfoption name="ldap suffix"/> string so use a partial DN.</para>
+
+</description>
+<value type="default"></value>
+<value type="example">ou=Groups</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapidmapsuffix.xml b/docs-xml/smbdotconf/ldap/ldapidmapsuffix.xml
new file mode 100644
index 0000000000..e397138741
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapidmapsuffix.xml
@@ -0,0 +1,15 @@
+<samba:parameter name="ldap idmap suffix"
+                 context="G"
+		 advanced="1" developer="1"
+		 type="string"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+	<para>
+	This parameters specifies the suffix that is used when storing idmap mappings. If this parameter 
+	is unset, the value of <smbconfoption name="ldap suffix"/> will be used instead.  The suffix 
+	string is pre-pended to the <smbconfoption name="ldap suffix"/> string so use a partial DN.
+	</para>
+</description>
+<value type="default"></value>
+<value type="example">ou=Idmap</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapmachinesuffix.xml b/docs-xml/smbdotconf/ldap/ldapmachinesuffix.xml
new file mode 100644
index 0000000000..b54f6383e8
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapmachinesuffix.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="ldap machine suffix"
+		context="G"
+		advanced="1"
+		developer="1"
+		type="string"
+		xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+
+<description>
+	<para>
+	It specifies where machines should be added to the ldap tree.  If this parameter is unset, the value of
+	<smbconfoption name="ldap suffix"/> will be used instead.  The suffix string is pre-pended to the
+	<smbconfoption name="ldap suffix"/> string so use a partial DN.
+	</para>
+</description>
+
+<value type="default"/>
+<value type="example">ou=Computers</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldappasswdsync.xml b/docs-xml/smbdotconf/ldap/ldappasswdsync.xml
new file mode 100644
index 0000000000..864bfc45a0
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldappasswdsync.xml
@@ -0,0 +1,38 @@
+<samba:parameter name="ldap passwd sync"
+			context="G"
+			advanced="1"
+			developer="1"
+			type="enum"
+			xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+
+<description>
+	<para>
+	This option is used to define whether or not Samba should sync the LDAP password with the NT
+	and LM hashes for normal accounts (NOT for workstation, server or domain trusts) on a password
+	change via SAMBA.  
+	</para>
+
+	<para>
+	The <smbconfoption name="ldap passwd sync"/> can be set to one of three values: 
+	</para>
+	
+	<itemizedlist>
+		<listitem>
+			<para><parameter moreinfo="none">Yes</parameter>  =  Try 
+			to update the LDAP, NT and LM passwords and update the pwdLastSet time.</para>
+		</listitem>
+			
+		<listitem>
+			<para><parameter moreinfo="none">No</parameter> = Update NT and 
+			LM passwords and update the pwdLastSet time.</para>
+		</listitem>
+
+		<listitem>
+			<para><parameter moreinfo="none">Only</parameter> = Only update 
+			the LDAP password and let the LDAP server do the rest.</para>
+		</listitem>
+	</itemizedlist>		
+</description>
+
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapreplicationsleep.xml b/docs-xml/smbdotconf/ldap/ldapreplicationsleep.xml
new file mode 100644
index 0000000000..4710e2b3b3
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapreplicationsleep.xml
@@ -0,0 +1,25 @@
+<samba:parameter name="ldap replication sleep"
+                 context="G"
+                 advanced="1" developer="1"
+				 type="integer"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+	<para>
+	When Samba is asked to write to a read-only LDAP replica, we are redirected to talk to the read-write master server.
+	This server then replicates our changes back to the 'local' server, however the replication might take some seconds, 
+	especially over slow links.  Certain client activities, particularly domain joins, can become confused by the 'success' 
+	that does not immediately change the LDAP back-end's data.
+	</para>
+        
+	<para>
+	This option simply causes Samba to wait a short time, to allow the LDAP server to catch up.  If you have a particularly
+	high-latency network, you may wish to time the LDAP replication with a network sniffer, and increase this value accordingly.  
+	Be aware that no checking is performed that the data has actually replicated.
+	</para>
+	
+        <para>
+	The value is specified in milliseconds, the maximum value is 5000 (5 seconds).
+	</para>
+</description>
+<value type="default">1000</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapsameditposix.xml b/docs-xml/smbdotconf/ldap/ldapsameditposix.xml
new file mode 100644
index 0000000000..ace6c6c64d
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapsameditposix.xml
@@ -0,0 +1,93 @@
+<samba:parameter name="ldapsam:editposix"
+	context="G"
+	type="string"
+		 advanced="1" developer="0"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+
+	<para>
+	Editposix is an option that leverages ldapsam:trusted to make it simpler to manage a domain controller
+	eliminating the need to set up custom scripts to add and manage the posix users and groups. This option
+	will instead directly manipulate the ldap tree to create, remove and modify user and group entries.
+	This option also requires a running winbindd as it is used to allocate new uids/gids on user/group
+	creation. The allocation range must be therefore configured.
+	</para>
+
+	<para>
+	To use this option, a basic ldap tree must be provided and the ldap suffix parameters must be properly
+	configured. On virgin servers the default users and groups (Administrator, Guest, Domain Users,
+	Domain Admins, Domain Guests) can be precreated with the command <command moreinfo="none">net sam
+	provision</command>. To run this command the ldap server must be running, Winindd must be running and
+	the smb.conf ldap options must be properly configured.
+
+	The typical ldap setup used with the <smbconfoption name="ldapsam:trusted">yes</smbconfoption> option
+	is usually sufficient to use <smbconfoption name="ldapsam:editposix">yes</smbconfoption> as well.
+	</para>
+
+	<para>
+	An example configuration can be the following:
+
+	<programlisting>
+	encrypt passwords = true
+	passdb backend = ldapsam
+
+	ldapsam:trusted=yes
+	ldapsam:editposix=yes
+
+	ldap admin dn = cn=admin,dc=samba,dc=org
+	ldap delete dn = yes
+	ldap group suffix = ou=groups
+	ldap idmap suffix = ou=idmap
+	ldap machine suffix = ou=computers
+	ldap user suffix = ou=users
+	ldap suffix = dc=samba,dc=org
+
+	idmap backend = ldap:"ldap://localhost"
+
+	idmap uid = 5000-50000
+	idmap gid = 5000-50000
+	</programlisting>
+
+	This configuration assume the ldap server have been loaded with a base tree like described
+	in the following ldif:
+
+	<programlisting>
+	dn: dc=samba,dc=org
+	objectClass: top
+	objectClass: dcObject
+	objectClass: organization
+	o: samba.org
+	dc: samba
+
+	dn: cn=admin,dc=samba,dc=org
+	objectClass: simpleSecurityObject
+	objectClass: organizationalRole
+	cn: admin
+	description: LDAP administrator
+	userPassword: secret
+
+	dn: ou=users,dc=samba,dc=org
+	objectClass: top
+	objectClass: organizationalUnit
+	ou: users
+
+	dn: ou=groups,dc=samba,dc=org
+	objectClass: top
+	objectClass: organizationalUnit
+	ou: groups
+
+	dn: ou=idmap,dc=samba,dc=org
+	objectClass: top
+	objectClass: organizationalUnit
+	ou: idmap
+
+	dn: ou=computers,dc=samba,dc=org
+	objectClass: top
+	objectClass: organizationalUnit
+	ou: computers
+	</programlisting>
+	</para>
+
+</description>
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapsamtrusted.xml b/docs-xml/smbdotconf/ldap/ldapsamtrusted.xml
new file mode 100644
index 0000000000..2e4e1dbd7c
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapsamtrusted.xml
@@ -0,0 +1,30 @@
+<samba:parameter name="ldapsam:trusted"
+	context="G"
+	type="string"
+		 advanced="1" developer="0"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+
+	<para>
+	By default, Samba as a Domain Controller with an LDAP backend needs to use the Unix-style NSS subsystem to
+	access user and group information. Due to the way Unix stores user information in /etc/passwd and /etc/group
+	this inevitably leads to inefficiencies. One important question a user needs to know is the list of groups he
+	is member of. The plain UNIX model involves a complete enumeration of the file /etc/group and its NSS
+	counterparts in LDAP. UNIX has optimized functions to enumerate group membership. Sadly, other functions that
+	are used to deal with user and group attributes lack such optimization.
+	</para>
+
+	<para>
+	To make Samba scale well in large environments, the <smbconfoption name="ldapsam:trusted">yes</smbconfoption>
+	option assumes that the complete user and group database that is relevant to Samba is stored in LDAP with the
+	standard posixAccount/posixGroup attributes. It further assumes that the Samba auxiliary object classes are 
+	stored together with the POSIX data in the same LDAP object. If these assumptions are met, 
+	<smbconfoption name="ldapsam:trusted">yes</smbconfoption> can be activated and Samba can bypass the 
+	NSS system to query user group memberships. Optimized LDAP queries can greatly speed up domain logon and 
+	administration tasks. Depending on the size of the LDAP database a factor of 100 or more for common queries 
+	is easily achieved.
+	</para>
+
+</description>
+<value type="default">no</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapssl.xml b/docs-xml/smbdotconf/ldap/ldapssl.xml
new file mode 100644
index 0000000000..39ed08fe82
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapssl.xml
@@ -0,0 +1,38 @@
+<samba:parameter name="ldap ssl"
+                 context="G"
+				 type="enum"
+                 advanced="1" developer="1"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+ <description>
+	<para>This option is used to define whether or not Samba should
+	use SSL when connecting to the ldap server
+	This is <emphasis>NOT</emphasis> related to
+	Samba's previous SSL support which was enabled by specifying the 
+	 <command moreinfo="none">--with-ssl</command> option to the <filename moreinfo="none">configure</filename> 
+	script.</para>
+		
+<para>The <smbconfoption name="ldap ssl"/> can be set to one of three values:</para>	
+	<itemizedlist>
+		<listitem>
+			<para><parameter moreinfo="none">Off</parameter> = Never 
+			use SSL when querying the directory.</para>
+		</listitem>
+
+		<listitem>
+			<para><parameter moreinfo="none">Start_tls</parameter> = Use 
+			the LDAPv3 StartTLS extended operation (RFC2830) for 
+			communicating with the directory server.</para>
+		</listitem>
+	    
+		<listitem>
+			<para><parameter moreinfo="none">On</parameter>  = Use SSL 
+			on the ldaps port when contacting the <parameter 
+			moreinfo="none">ldap server</parameter>. Only available when the 
+			backwards-compatiblity <command 
+			moreinfo="none">--with-ldapsam</command> option is specified
+		to configure. See <smbconfoption name="passdb backend"/></para>.
+		</listitem>
+	</itemizedlist>		
+</description>
+<value type="default">start_tls</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapsuffix.xml b/docs-xml/smbdotconf/ldap/ldapsuffix.xml
new file mode 100644
index 0000000000..48595139a2
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapsuffix.xml
@@ -0,0 +1,18 @@
+<samba:parameter name="ldap suffix"
+                 context="G"
+		 type="string"
+		 advanced="1" developer="1"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+	<para>Specifies the base for all ldap suffixes and for storing the sambaDomain object.</para>
+
+	<para>
+	The ldap suffix will be appended to the values specified for the <smbconfoption name="ldap user suffix"/>,
+	 <smbconfoption name="ldap group suffix"/>, <smbconfoption name="ldap machine suffix"/>, and the
+	 <smbconfoption name="ldap idmap suffix"/>. Each of these should be given only a DN relative to the
+	 <smbconfoption name ="ldap suffix"/>.
+	</para>
+</description>
+<value type="default"></value>
+<value type="example">dc=samba,dc=org</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldaptimeout.xml b/docs-xml/smbdotconf/ldap/ldaptimeout.xml
new file mode 100644
index 0000000000..cd88494903
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldaptimeout.xml
@@ -0,0 +1,14 @@
+<samba:parameter name="ldap timeout"
+                 context="G"
+                 advanced="1" developer="1"
+				 type="integer"
+                 xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+	<para>
+	When Samba connects to an ldap server that servermay be down or unreachable. To prevent Samba from hanging whilst
+	waiting for the connection this parameter specifies in seconds how long Samba should wait before failing the 
+	connect. The default is to only wait fifteen seconds for the ldap server to respond to the connect request.
+	</para>
+</description>
+<value type="default">15</value>
+</samba:parameter>
diff --git a/docs-xml/smbdotconf/ldap/ldapusersuffix.xml b/docs-xml/smbdotconf/ldap/ldapusersuffix.xml
new file mode 100644
index 0000000000..6b4eec378d
--- /dev/null
+++ b/docs-xml/smbdotconf/ldap/ldapusersuffix.xml
@@ -0,0 +1,16 @@
+<samba:parameter name="ldap user suffix"
+	context="G"
+	type="string"
+	advanced="1" developer="1"
+        xmlns:samba="http://www.samba.org/samba/DTD/samba-doc">
+<description>
+	<para>
+	This parameter specifies where users are added to the tree. If this parameter is unset, 
+	the value of <smbconfoption name="ldap suffix"/> will be used instead.  The suffix 
+	string is pre-pended to the  <smbconfoption name="ldap suffix"/> string so use a partial DN.
+	</para>
+
+</description>
+<value type="default"/>
+<value type="example">ou=people</value>
+</samba:parameter>