Updating documentation for 3.0.23. Jerry, please check these changes.

(This used to be commit fc676238b8e21f244073a9da8cde0f24386c02ea)

7 files changed, 211 insertions, 18 deletions

diff --git a/docs/Samba3-HOWTO/TOSHARG-ChangeNotes.xml b/docs/Samba3-HOWTO/TOSHARG-ChangeNotes.xml
new file mode 100644
index 0000000000..ec7b75100a
--- /dev/null
+++ b/docs/Samba3-HOWTO/TOSHARG-ChangeNotes.xml
@@ -0,0 +1,177 @@
+<?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="ChangeNotes">
+<chapterinfo>
+	&author.jht;
+	&author.jerry;
+</chapterinfo>
+
+<title>Important Samba-3.0.23 Change Notes</title>
+
+<para>
+Samba is a fluid and ever changing project. Sometimes it is difficult to figure out which part,
+or parts, of the HOWTO documentation should be updated tio reflect the impact of new or modified
+features. At other times it becomes clear that the documentation is in need of being restructured.
+</para>
+
+<para>
+In recent times a group of Samba users has joined the thrust to create a new <ulink
+url="http://wiki.samba.org/">Samba Wiki</ulink> that is slated to become the all-singing and all-dancing
+new face of Samba documentation. Hopefully, the Wiki will benefit from greater community input and
+thus may be kept more up to date. Until that golden dream materializes and matures it is necessary to
+continue to maintain the HOWTO. This chapter will document major departures from earlier behavior until
+such time as the body of this HOWTO is restructured or modified.
+</para>
+
+<para>
+This chapter is new to the release of the HOWTO for Samba 3.0.23. It includes much of the notes provided
+in the <filename>WHATSNEW.txt</filename> file that is included with the Samba source code release tarball.
+</para>
+
+<sect1>
+<title>User and Group Changes</title>
+
+<para>
+The change documented here affects unmapped user and group accounts only.
+</para>
+
+<para>
+<indexterm><primary>user</primary></indexterm>
+<indexterm><primary>group</primary></indexterm>
+<indexterm><primary>Relative Identifiers</primary><see>RID</see></indexterm>
+<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm>
+<indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>vampire</tertiary></indexterm>
+The user and group internal management routines have been rewritten to prevent overlaps of
+assigned Relative Identifiers (RIDs).  In the past the has been a potential problem when
+either manually mapping Unix groups with the <command>net groupmap</command> command or
+when migrating a Windows domain to a Samba domain by executing:
+<command>net rpc vampire</command>.
+</para>
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>SAM</primary></indexterm>
+<indexterm><primary>RID</primary></indexterm>
+<indexterm><primary>net</primary><secondary>getlocalsid</secondary></indexterm>
+Unmapped users are now assigned a SID in the <literal>S-1-22-1</literal> domain and unmapped
+groups are assigned a SID in the <literal>S-1-22-2</literal> domain.  Previously they were
+assign a RID within the SAM on the Samba server.  For a domain controller this would have been under the
+authority of the domain SID where as on a member server or standalone server, this would have
+been under the authority of the local SAM (see the man page for <command>net getlocalsid</command>).
+</para>
+
+<para>
+<indexterm><primary>unmapped users</primary></indexterm>
+<indexterm><primary>unmapped groups</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>NTFS</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+The result is that any unmapped users or groups on an upgraded Samba domain controller may
+be assigned a new SID.  Because the SID rather than a name is stored in Windows security
+descriptors, this can cause a user to no longer have access to a resource for example if a
+file was copied from a Samba file server to a local Windows client NTFS partition.  Any files
+stored on the Samba server itself will continue to be accessible because UNIX stores the UNIX
+GID and not the SID for authorization checks.
+</para>
+
+<para>
+An example helps to illustrate the change:
+</para>
+
+<para>
+<indexterm><primary>group mapping</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>ACL</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+Assume that a group named <emphasis>developers</emphasis> exists with a UNIX GID of 782. In this
+case this user does not exist in Samba's group mapping table. It would be perfectly normal for
+this group to be appear in an ACL editor.  Prior to Samba-3.0.23, the group SID might appear as
+<literal>S-1-5-21-647511796-4126122067-3123570092-2565</literal>. 
+</para>
+
+<para>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>NTFS</primary></indexterm>
+<indexterm><primary>access</primary></indexterm>
+<indexterm><primary>group permissions</primary></indexterm>
+With the release of Samba-3.0.23, the group SID would be reported as <literal>S-1-22-2-782</literal>.
+Any security descriptors associated with files stored on a Windows NTFS disk partition will not allow
+access based on the group permissions if the user was not a member of the
+<literal>S-1-5-21-647511796-4126122067-3123570092-2565</literal>  group. 
+Because this group SID is <literal>S-1-22-2-782</literal> and not reported in a user's token,
+Windows would fail the authorization check even though both SIDs in some respect refer to the
+same UNIX group.
+</para>
+
+<para>
+<indexterm><primary>group mapping</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+The workaround for versions of Samba prior to 3.0.23, is to create a manual domain group mapping
+entry for the group <emphasis>developers</emphasis> to point at the
+<literal>S-1-5-21-647511796-4126122067-3123570092-2565</literal> SID. With the release of Samba-3.0.23 this
+workaround is no longer needed.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Passdb Changes</title>
+
+<para>
+<indexterm><primary>backends</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>SQL</primary></indexterm>
+<indexterm><primary>XML</primary></indexterm>
+The <smbconfoption name="passdb backend"/> parameter no long accepts multiple passdb backends in a
+chained configuration.  Also be aware that the SQL and XML based passdb modules have been
+removed in the Samba-3.0.23 release.  More information regarding external support for a SQL
+passdb module can be found on the  <ulink url="http://pdbsql.sourceforge.net/">pdbsql</ulink web site.
+</para>
+
+</sect1>
+
+<sect1>
+<title>Group Mapping Changes in Samba-3.0.23</title>
+
+<para>
+<indexterm><primary>default mapping</primary></indexterm>
+<indexterm><primary>Domain Admins</primary></indexterm>
+<indexterm><primary>smbpasswd</primary></indexterm>
+<indexterm><primary>tdbsam</primary></indexterm>
+<indexterm><primary>passdb backend</primary></indexterm>
+<indexterm><primary>group mappings</primary></indexterm>
+<indexterm><primary>GID</primary></indexterm>
+<indexterm><primary>SID</primary></indexterm>
+<indexterm><primary>IDMAP</primary></indexterm>
+<indexterm><primary>winbindd</primary></indexterm>
+<indexterm><primary>domain groups</primary></indexterm>
+The default mapping entries for groups such as <literal>Domain Admins</literal> are no longer
+created when using an <literal>smbpasswd</literal> file or a <literal>tdbsam</literal> passdb
+backend.  This means that it is necessary to explicitly execute the <command>net groupmap add</command>
+to create group mappings, rather than use the <command>net groupmap modify</command> method to create the
+Windows group SID to UNIX GID mappings.  This change has no effect on winbindd's IDMAP functionality
+for domain groups.
+</para>
+
+</sect1>
+
+<sect1>
+<title>LDAP Changes in Samba-3.0.23</title>
+
+<para>
+<indexterm><primary>LDAP schema</primary></indexterm>
+<indexterm><primary>sambaSID</primary></indexterm>
+<indexterm><primary>OpenLDAP</primary></indexterm>
+<indexterm><primary>slapindex</primary></indexterm>
+<indexterm><primary>slapd.conf</primary></indexterm>
+There has been a minor update the Samba LDAP schema file. A substring matching rule has been
+added to the <literal>sambaSID</literal> attribute definition.  For OpenLDAP servers, this
+will require the addition of <literal>index sambaSID sub</literal> to the
+<filename>slapd.conf</filename> configuration file.  It will be necessary to execute the 
+<command>slapindex</command> command after making this change. There has been no change to the
+actual data storage schema.
+</para>
+
+</sect1>
+
+</chapter>
diff --git a/docs/Samba3-HOWTO/TOSHARG-FastStart.xml b/docs/Samba3-HOWTO/TOSHARG-FastStart.xml
index 25924b9b3f..ff2552515b 100644
--- a/docs/Samba3-HOWTO/TOSHARG-FastStart.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-FastStart.xml
@@ -1022,9 +1022,9 @@ maryo:x:15000:15003:Mary Orville:/home/MIDEARTH/maryo:/bin/false
 #### Keep this as a shell script for future re-use
 			
 # First assign well known groups
-net groupmap modify ntgroup="Domain Admins" unixgroup=ntadmins
-net groupmap modify ntgroup="Domain Users"  unixgroup=users
-net groupmap modify ntgroup="Domain Guests" unixgroup=nobody
+net groupmap add ntgroup="Domain Admins" unixgroup=ntadmins rid=512 type=d
+net groupmap add ntgroup="Domain Users"  unixgroup=users rid=513 type=
+net groupmap add ntgroup="Domain Guests" unixgroup=nobody rid=514 type=d
 
 # Now for our added Domain Groups
 net groupmap add ntgroup="Designers" unixgroup=designers type=d
diff --git a/docs/Samba3-HOWTO/TOSHARG-Group-Mapping.xml b/docs/Samba3-HOWTO/TOSHARG-Group-Mapping.xml
index 984a17e53e..337ae3d794 100644
--- a/docs/Samba3-HOWTO/TOSHARG-Group-Mapping.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-Group-Mapping.xml
@@ -19,7 +19,7 @@
 <indexterm><primary>groupmap</primary></indexterm>
 <indexterm><primary>net</primary></indexterm>
 	Starting with Samba-3, new group mapping functionality is available to create associations
-	between Windows group SIDs and UNIX groups. The <command>groupmap</command> subcommand
+	between Windows group SIDs and UNIX group GIDs. The <command>groupmap</command> subcommand
 	included with the &net; tool can be used to manage these associations.
 	</para>
 
@@ -183,12 +183,12 @@
 		</para></listitem>
 
 		<listitem><para>
-		Map this domadm group to the <quote>Domain Admins</quote> group by running the command:
+		Map this domadm group to the <quote>Domain Admins</quote> group by executing the command:
 		</para>
 
 		<para>
 <screen>
-&rootprompt;<userinput>net groupmap add ntgroup="Domain Admins" unixgroup=domadm</userinput>
+&rootprompt;<userinput>net groupmap add ntgroup="Domain Admins" unixgroup=domadm rid=512 type=d</userinput>
 </screen>
 		</para>
 		
@@ -213,7 +213,7 @@
 
 	<para>
 <screen>
-&rootprompt;<userinput>net groupmap add rid=1000 ntgroup="Accounting" unixgroup=acct</userinput>
+&rootprompt;<userinput>net groupmap add rid=1000 ntgroup="Accounting" unixgroup=acct type=d</userinput>
 </screen>
 	The <literal>ntgroup</literal> value must be in quotes if it contains space characters to prevent
 	the space from being interpreted as a command delimiter.
@@ -350,7 +350,7 @@
 <indexterm><primary>alias group</primary></indexterm>
 	In effect, Samba supplements the <filename>/etc/group</filename> data via the dynamic
 	<command>libnss_winbind</command> mechanism. Beginning with Samba-3.0.3, this facility is used to provide
-	local groups in the same manner as Windows does it. It works by expanding the local groups on the
+	local groups in the same manner as Windows. It works by expanding the local groups on the
 	fly as they are accessed. For example, the <constant>Domain Users</constant> group of the domain is made
 	a member of the local group <constant>demo</constant>. Whenever Samba needs to resolve membership of the
 	<constant>demo</constant> local (alias) group, winbind asks the domain controller for demo members of the Domain Users
@@ -509,8 +509,8 @@
 <indexterm><primary>ldapsam</primary></indexterm>
 <indexterm><primary>domain groups</primary></indexterm>
 <indexterm><primary>RID</primary></indexterm>
-	When the <parameter>passdb backend</parameter> uses LDAP (<constant>ldapsam</constant>), it is the
-	administrator's responsibility to create the essential domain groups and to assign each its default RID.
+	It is the administrator's responsibility to create the essential domain groups and to assign each
+	its default RID.
 	</para></note>
 
 	<para>
@@ -785,9 +785,9 @@ exit 0
 <programlisting>
 #!/bin/bash
 
-net groupmap modify ntgroup="Domain Admins" unixgroup=ntadmin
-net groupmap modify ntgroup="Domain Users" unixgroup=users
-net groupmap modify ntgroup="Domain Guests" unixgroup=nobody
+net groupmap add ntgroup="Domain Admins" unixgroup=ntadmin rid=512 type=d
+net groupmap add ntgroup="Domain Users" unixgroup=users rid=513 type=d
+net groupmap add ntgroup="Domain Guests" unixgroup=nobody rid=514 type=d
 
 groupadd Orks
 groupadd Elves
@@ -806,6 +806,15 @@ net groupmap add ntgroup="Gnomes" unixgroup=Gnomes type=d
 	refer to the man page.
 	</para>
 
+	<note><para>
+	Versions of Samba-3 prior to 3.0.23 automatically create default group mapping for the
+	<literal>Domain Admins, Domain Users</literal> and <literal>Domain Guests</literal> Windows
+	groups, but do not map them to UNIX GIDs. This was a cause of administrative confusion and 
+	trouble. Commencing with Samba-3.0.23 this annomaly has been fixed - thus all Windows groups
+	must now be manually and explicitly created and mapped to a valid UNIX GID by the Samba 
+	administrator.
+	</para></note>
+
 	</sect2>
 
 </sect1>
diff --git a/docs/Samba3-HOWTO/TOSHARG-NT4Migration.xml b/docs/Samba3-HOWTO/TOSHARG-NT4Migration.xml
index 172911127d..2688e060ac 100644
--- a/docs/Samba3-HOWTO/TOSHARG-NT4Migration.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-NT4Migration.xml
@@ -362,9 +362,9 @@ The approximate migration process is described below.
 #### Keep this as a shell script for future re-use
 			
 # First assign well known domain global groups
-net groupmap modify ntgroup="Domain Admins" unixgroup=root
-net groupmap modify ntgroup="Domain Users"  unixgroup=users
-net groupmap modify ntgroup="Domain Guests" unixgroup=nobody
+net groupmap add ntgroup="Domain Admins" unixgroup=root rid=512 type=d
+net groupmap add ntgroup="Domain Users"  unixgroup=users rid=513 type=d
+net groupmap add ntgroup="Domain Guests" unixgroup=nobody rid=514 type=d
 
 # Now for our added domain global groups
 net groupmap add ntgroup="Designers" unixgroup=designers type=d
diff --git a/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml b/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml
index a7cd9d457e..b2b3ebd5b1 100644
--- a/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-TheNetCommand.xml
@@ -340,6 +340,11 @@ SupportEngrs (S-1-5-21-72630-4128915-11681869-3007) -> SupportEngrs
 	and <constant>delete</constant>. An example of each operation is shown here.
 	</para>
 
+	<note><para>
+	Commencing with Samba-3.0.23 Windows Domain Groups must be explicitly created. By default, all
+	UNIX groups are exposed to Windows networking as Windows local groups.
+	</para></note>
+
 	<para>
 	An existing UNIX group may be mapped to an existing Windows group by this example:
 <screen>
diff --git a/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml b/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml
index 55743a734a..74d39c3d5d 100644
--- a/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml
+++ b/docs/Samba3-HOWTO/TOSHARG-upgrading-to-3.0.xml
@@ -181,8 +181,8 @@ parameters.
 <para>
 Whenever a Samba update or upgrade is performed it is highly recommended to read the file called
 <emphasis>WHATSNEW.txt</emphasis> that is part of the Samba distribution tarball. This file may also
-be obtain on-line from <ulink url="http://www.samba.org/samba/">Samba web site, in the right column, under
-Current Stable Release, by clicking on <emphasis>Release Notes</emphasis>.
+be obtain on-line from the Samba <ulink url="http://www.samba.org/samba/">web site</ulink>, in 
+the right column, under Current Stable Release, by clicking on <emphasis>Release Notes</emphasis>.
 </para>
 
 <sect2>
diff --git a/docs/Samba3-HOWTO/index.xml b/docs/Samba3-HOWTO/index.xml
index 7bbc7dce8c..3ac9740620 100644
--- a/docs/Samba3-HOWTO/index.xml
+++ b/docs/Samba3-HOWTO/index.xml
@@ -115,6 +115,8 @@ The chapters in this part each cover specific Samba features.
 </partintro>
 
 	<?latex \cleardoublepage ?>
+	<xi:include href="TOSHARG-ChangeNotes.xml"/>
+	<?latex \cleardoublepage ?>
 	<xi:include href="TOSHARG-NetworkBrowsing.xml"/>
 	<?latex \cleardoublepage ?>
 	<xi:include href="TOSHARG-Passdb.xml"/>