Updating documentation of tdb files some more.

(This used to be commit 9d530b84d791feaeb1a77bca37e91557adf86f14)

6 files changed, 269 insertions, 32 deletions

diff --git a/docs/Samba3-HOWTO/TOSHARG-CUPS-printing.xml b/docs/Samba3-HOWTO/TOSHARG-CUPS-printing.xml
index 081fd597ba..e76aeeae7d 100644
--- a/docs/Samba3-HOWTO/TOSHARG-CUPS-printing.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-CUPS-printing.xml
@@ -2366,7 +2366,7 @@ Windows. The CUPS driver is derived from the Microsoft one.
 <para>
 In an attempt to work around problems, site administrators have resorted to restricting the
 allowed drivers installed on their WTS to one generic PCL and one PostScript driver. This, however, restricts
-the the number of printer options available for clients to use. Often they can't get out more than simplex
+the number of printer options available for clients to use. Often they can't get out more than simplex
 prints from one standard paper tray, while their devices could do much better if driven by a different driver!
 </para>
 </sect2>
diff --git a/docs/Samba3-HOWTO/TOSHARG-Install.xml b/docs/Samba3-HOWTO/TOSHARG-Install.xml
index c8655c91fb..769e0b10cf 100644
--- a/docs/Samba3-HOWTO/TOSHARG-Install.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-Install.xml
@@ -119,6 +119,193 @@
 
 </sect2>
 
+<sect2 id="tdbdocs">
+	<title>TDB Database File Information</title>
+
+	<para>
+	This section contains brief descriptions of the databases that are used by Samba-3.
+	</para>
+
+	<para>
+<indexterm><primary>tdb file locations</primary></indexterm>
+	The directory in which Samba stores the tdb files is determined by compile-time directives. Samba-3 stores
+	tdb files in two locations. The best way to determine these locations is to execute the following
+	command:
+<screen>
+&rootprompt; smbd -b | grep PRIVATE_DIR
+   PRIVATE_DIR: /etc/samba/private
+</screen>
+	This means that the confidential tdb files are stored in the <filename>/etc/samba/private</filename>
+	directory. Samba-3 also uses a number of tdb files that contain more mundane data. The location of
+	these files can be found by executing:
+<screen>
+&rootprompt; smbd -b | grep LOCKDIR
+   LOCKDIR: /var/lib/samba
+</screen>
+	Therefore the remaining control files will, in the example shown, be stored in the
+	<filename>/var/lib/samba</filename> directory.
+	</para>
+
+	<para>
+<indexterm><primary>tdb file descriptions</primary></indexterm>
+	The persistent tdb files are described in <link linkend="tdbpermfiledesc">the Persistent TDB File
+	Descriptions table</link>. All persistent tdb files should be regularly backed up. Use the
+	<command>tdbbackup</command> utility to backup the tdb files. All persistent tdb files must be
+	preserved during machine migrations, updates and upgrades.
+	</para>
+
+	<para>
+	The temporary tdb files do not need to be backed up, nor do they need to be preseved across machine
+	migrations, updates or upgrades. The temporary tdb files are described in <link linkend="tdbtempfiledesc">
+	the Temporary TDB File Descriptions</link>.
+	</para>
+
+        <table frame='all' id="tdbpermfiledesc"><title>Persistent TDB File Descriptions</title>
+        <tgroup cols='2'>
+			<colspec align="left"/>
+			<colspec align="justify" colwidth="1*"/>
+			<colspec align="left"/>
+                <thead>
+                <row>
+                        <entry align="left">Name</entry>
+                        <entry align="justify">Description</entry>
+                </row>
+                </thead>
+                <tbody>
+		<row>
+			<entry>account_policy</entry>
+			<entry><para>User policy settings.</para></entry>
+		</row>
+		<row>
+			<entry>group_mapping</entry>
+			<entry><para>Mapping table from Windows groups/SID to UNIX groups.</para></entry>
+		</row>
+		<row>
+			<entry>ntdrivers</entry>
+			<entry><para>Stores per-printer driver information.</para></entry>
+		</row>
+		<row>
+			<entry>ntforms</entry>
+			<entry><para>Stores per-printer forms information.</para></entry>
+		</row>
+		<row>
+			<entry>ntprinters</entry>
+			<entry><para>Stores the per-printer devmode configuration settings.</para></entry>
+		</row>
+		<row>
+			<entry>passdb</entry>
+			<entry><para>
+				Exists only when the tdbsam passwd backend is used. This file stores the
+				SambaSAMAccount information. Note: This file requires that user POSIX account information is
+				availble from either the /etc/passwd file, or from an alternative system source.
+			</para></entry>
+		</row>
+		<row>
+			<entry>registry</entry>
+			<entry><para>
+				Read-only Samba registry skeleton that provides support for exporting various database tables
+				via the winreg RPCs.
+			</para></entry>
+		</row>
+		<row>
+			<entry>secrets</entry>
+			<entry><para>
+				This file stores the Workgroup/Domain/Machine SID, the LDAP directory update password, and
+				a further collection of critical environmental data that is necessary for Samba to operate
+				correctly. This file contains very sensitive information that must be protected. It is stored
+				in the PRIVARE_DIR directory.
+			</para></entry>
+		</row>
+		<row>
+			<entry>share_info</entry>
+			<entry><para>Stores per-share ACL information.</para></entry>
+		</row>
+		<row>
+			<entry>winbindd_idmap</entry>
+			<entry><para>New ID map table from SIDS to UNIX UIDs/GIDs.</para></entry>
+		</row>
+		</tbody>
+	</tgroup>
+	</table>
+
+        <table frame='all' id="tdbtempfiledesc"><title>Temporary TDB File Descriptions</title>
+        <tgroup cols='3'>
+			<colspec align="left"/>
+			<colspec align="justify" colwidth="1*"/>
+			<colspec align="left"/>
+                <thead>
+                <row>
+                        <entry align="left">Name</entry>
+                        <entry align="justify">Description</entry>
+                        <entry align="center">Backup</entry>
+                </row>
+                </thead>
+                <tbody>
+		<row>
+			<entry>brlock</entry>
+			<entry><para>Byte-range locking information.</para></entry>
+			<entry>No</entry>
+		</row>
+		<row>
+			<entry>connections</entry>
+			<entry><para>A temporary cache for current connection information.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>gencache</entry>
+			<entry><para>Generic caching database for dead WINS servers and trusted domain data.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>login_cache</entry>
+			<entry><para>A temporary cache for login information.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>messages</entry>
+			<entry><para>Temporary storage of messages being processed by smbd.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>netsamlogon_cache</entry>
+			<entry><para>Packets received for which no process is listening.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>printing/*.tdb</entry>
+			<entry><para>Cached output from lpq command created on a per-print-service basis.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>schannel_store</entry>
+			<entry><para>
+				A confidential file, stored in the PRIVATE_DIR, containing crytographic connection
+				information so that clients that have temporarily disconnected can reconnect without
+				needing to renegotiate the connection setup process.
+			</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>sessionid</entry>
+			<entry><para>Temporary cache for miscellaneous session information.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>unexpected</entry>
+			<entry><para>Stores packets received for which no process is actively listening.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>winbindd_cache</entry>
+			<entry><para>Cache of Identity information received from an NT4 domain or from ADS.</para></entry>
+			<entry>yes</entry>
+		</row>
+		</tbody>
+	</tgroup>
+	</table>
+
+</sect2>
+
 <sect2>
 	<title>Starting Samba</title>
 
diff --git a/docs/Samba3-HOWTO/TOSHARG-PDC.xml b/docs/Samba3-HOWTO/TOSHARG-PDC.xml
index 715c92710c..31a828b83e 100644
--- a/docs/Samba3-HOWTO/TOSHARG-PDC.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-PDC.xml
@@ -550,7 +550,7 @@ time choices offered are:
 <note><para>
 <indexterm><primary>promote</primary></indexterm>
 Algin Technology LLC provide a commercial tool that makes it possible to promote a Windows NT4 standalone
-server to a PDC or a BDC, and also permits this process to be reversed. Refer the the <ulink
+server to a PDC or a BDC, and also permits this process to be reversed. Refer to the <ulink
 url="http://utools.com/UPromote.asp">Algin</ulink> web site for further information.
 </para></note>
 
diff --git a/docs/Samba3-HOWTO/TOSHARG-Printing.xml b/docs/Samba3-HOWTO/TOSHARG-Printing.xml
index 2ccb953d56..1cf35fb7c4 100644
--- a/docs/Samba3-HOWTO/TOSHARG-Printing.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-Printing.xml
@@ -2978,7 +2978,7 @@ not be disabled.
 <title>The Installation Client</title>
 
 <para>
-More information regarding the Imprints installation client is available from the the documentation file
+More information regarding the Imprints installation client is available from the documentation file
 <filename>Imprints-Client-HOWTO.ps</filename> that is included with the Imprints source package. The Imprints
 installation client comes in two forms:
 </para>
diff --git a/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml b/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml
index 2ca199c132..a7cd9d457e 100644
--- a/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml
@@ -1617,7 +1617,7 @@ net rpc share MIGRATE ALL &lt;share-name&gt; -S &lt;source&gt;
 	<para>
 	The installation of a new server, as with the migration to a new network environment, often is similar to
 	building a house; progress is very rapid from the laying of foundations up to the stage at which
-	the the house can be locked up, but the finishing off appears to take longer and longer as building
+	the house can be locked up, but the finishing off appears to take longer and longer as building
 	approaches completion.
 	</para>
 
@@ -1830,8 +1830,8 @@ net ads printer search &lt;printer_name&gt; -Uadministrator%secret
 <screen>
 net idmap dump &lt;full_path_and_tdb_filename&gt; &gt; dumpfile.txt
 </screen>
-	Where the Samba run-time tdb files are stored in the <filename>/var/lib/samba</filename> directory
-	the the following commands to create the dump file will suffice:
+	Where a particular build of Samba the run-time tdb files are stored in the
+	<filename>/var/lib/samba</filename> directory the following commands to create the dump file will suffice:
 <screen>
 net idmap dump /var/lib/samba/winbindd_idmap.tdb &gt; idmap_dump.txt
 </screen>
@@ -1848,7 +1848,7 @@ net idmap dump /var/lib/samba/winbindd_idmap.tdb &gt; idmap_dump.txt
 net idmap restore &lt;full_path_and_tdb_filename&gt; &lt; dumpfile.txt
 </screen>
 	Where the Samba run-time tdb files are stored in the <filename>/var/lib/samba</filename> directory
-    the the following command can be used to restore the data to the tdb file:
+    the following command can be used to restore the data to the tdb file:
 <screen>
 net idmap restore /var/lib/samba/winbindd_idmap.tdb &lt; idmap_dump.txt
 </screen>
diff --git a/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml b/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml
index aada0978d8..057e72b10a 100644
--- a/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml
@@ -395,23 +395,38 @@ In alphabetical order, these are the parameters eliminated from Samba-2.2.x thro
 <sect1>
 <title>New Functionality</title>
 
+	<para>
+<indexterm><primary>major changes</primary></indexterm>
+	The major changes in behavior since that Samba-2.2.x series are documented in this section.
+	Please refer to the <filename>WHATSNEW.txt</filename> file that ships with every release of
+	Samba to obtain detailed information regarding the changes that have been made during the
+	life of the current Samba release.
+	</para>
+
 	<sect2>
-	<title>Databases</title>
+	<title>TDB Data Files</title>
+
+<indexterm><primary>tdb data files</primary></indexterm>
+	<para>
+	Refer to <link linkend="install">Installation, Chapter 1</link>, <link linkend="tdbdocs">Chapter 1</link>
+	for information pertaining to the Samba-3 data files, their location and the information that must be
+	preserved across server migrations, updates and upgrades.
+	</para>
 
 	<para>
-	This section contains brief descriptions of any new databases
-	introduced in Samba-3. Please remember to back up your existing
-	${lock directory}/*tdb before upgrading to Samba-3. Samba will
-	upgrade databases as they are opened (if necessary), but downgrading
-	from 3.0 to 2.2 is an unsupported path.
+<indexterm><primary>tdb file backup</primary></indexterm>
+	Please remember to back up your existing ${lock directory}/*tdb before upgrading to Samba-3. If necessary, Samba will 
+	upgrade databases as they are opened. Downgrading from Samba-3 to 2.2, or reversion to an earlier version
+	of Samba-3 from a later release, is an unsupported path.
 	</para>
 
 	<para>
-	The new tdb files are described in <link linkend="tdbfiledesc">the next table</link>.
+<indexterm><primary>tdb file descriptions</primary></indexterm>
+	The old Samba-2.2.x tdb files are described in <link linkend="oldtdbfiledesc">the next table</link>.
 	</para>
 
 
-        <table frame='all' id="tdbfiledesc"><title>TDB File Descriptions</title>
+        <table frame='all' id="oldtdbfiledesc"><title>Samba-2.2.x TDB File Descriptions</title>
         <tgroup cols='3'>
 			<colspec align="left"/>
 			<colspec align="justify" colwidth="1*"/>
@@ -430,43 +445,78 @@ In alphabetical order, these are the parameters eliminated from Samba-2.2.x thro
 			<entry>yes</entry>
 		</row>
 		<row>
-			<entry>gencache</entry>
-			<entry>Generic caching db</entry>
+			<entry>brlock</entry>
+			<entry>Byte-range file locking information.</entry>
 			<entry>no</entry>
 		</row>
 		<row>
-			<entry>group_mapping</entry>
-			<entry><para>Mapping table from Windows groups/SID to UNIX groups</para></entry>
-			<entry>yes</entry>
-		</row>
-		<row>
-			<entry>idmap</entry>
-			<entry><para>New ID map table from SIDS to UNIX UIDs/GIDs</para></entry>
-			<entry>yes</entry>
+			<entry>connections</entry>
+			<entry><para>Client connection information</para></entry>
+			<entry>no</entry>
 		</row>
 		<row>
-			<entry>namecache</entry>
-			<entry>Name resolution cache entries</entry>
+			<entry>locking</entry>
+			<entry>Temporary file locking data.</entry>
 			<entry>no</entry>
 		</row>
 		<row>
-			<entry>netlogon_unigrp</entry>
-			<entry><para>Cache of universal group membership obtained when operating
-				as a member of a Windows domain</para></entry>
+			<entry>messages</entry>
+			<entry><para>Temporary storage of messages being processed by smbd.</para></entry>
 			<entry>no</entry>
 		</row>
+       <row>
+            <entry>ntdrivers</entry>
+            <entry><para>Stores per-printer driver information.</para></entry>
+			<entry>yes</entry>
+        </row>
+        <row>
+            <entry>ntforms</entry>
+            <entry><para>Stores per-printer forms information.</para></entry>
+			<entry>yes</entry>
+        </row>
+        <row>
+            <entry>ntprinters</entry>
+            <entry><para>Stores the per-printer devmode configuration settings.</para></entry>
+			<entry>yes</entry>
+        </row>
 		<row>
 			<entry>printing/*.tdb</entry>
-			<entry><para>Cached output from lpq command created on a per-print-service basis</para></entry>
+			<entry><para>Cached output from lpq command created on a per-print-service basis.</para></entry>
 			<entry>no</entry>
 		</row>
 		<row>
 
 			<entry>registry</entry>
 			<entry><para>Read-only Samba registry skeleton that provides support for
-				exporting various database tables via the winreg RPCs</para></entry>
+				exporting various database tables via the winreg RPCs.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>sessionid</entry>
+			<entry><para>Temporary cache for miscellaneous session information.</para></entry>
 			<entry>no</entry>
 		</row>
+		<row>
+			<entry>share_info</entry>
+			<entry>Share ACL settings.</entry>
+			<entry>yes</entry>
+		</row>
+		<row>
+
+			<entry>unexpected</entry>
+			<entry><para>Packets received for which no process was listening.</para></entry>
+			<entry>no</entry>
+		</row>
+		<row>
+			<entry>winbindd_cache</entry>
+			<entry><para>Cache of identity information received from an NT4 or an ADS domain.</para></entry>
+			<entry>yes</entry>
+		</row>
+		<row>
+			<entry>winbindd_idmap</entry>
+			<entry><para>New ID map table from SIDS to UNIX UIDs/GIDs.</para></entry>
+			<entry>yes</entry>
+		</row>
 		</tbody>
 	</tgroup>
 	</table>