trying to get HEAD building again. If you want the code

prior to this merge, checkout HEAD_PRE_3_0_0_BETA_3_MERGE
(This used to be commit adb98e7b7cd0f025b52c570e4034eebf4047b1ad)

1 files changed, 280 insertions, 71 deletions

diff --git a/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml b/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml
index af6ddff9bf..a13a43675b 100644
--- a/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml
+++ b/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml
@@ -5,100 +5,309 @@
 		<firstname>Jean François</firstname><surname>Micouleau</surname>
 	</author>
 	&author.jerry;
+	&author.jht;
 </chapterinfo>
+<title>Mapping MS Windows and Unix Groups</title>
 
-<title>Configuring Group Mapping</title>
+	<para>
+	Starting with Samba-3, new group mapping functionality is available to create associations
+	between Windows group SIDs and UNIX groups. The <parameter>groupmap</parameter> subcommand
+	included with the &net; tool can be used to manage these associations.
+	</para>
 
-<para>
-Starting with Samba 3.0 alpha 2, new group mapping functionality
-is available to create associations between Windows SIDs and UNIX
-groups. The <parameter>groupmap</parameter> subcommand included with
-the <command>net</command> tool can be used to manage these associations.
-</para>
+	<warning>
+	<para>
+	The first immediate reason to use the group mapping on a Samba PDC, is that
+	the <parameter>domain admin group</parameter> has been removed and should no longer
+	be specified in &smb.conf;. This parameter was used to give the listed users membership
+	in the <constant>Domain Admins</constant> Windows group which gave local admin rights on their workstations
+	(in default configurations).
+	</para>
+	</warning>
 
-<para>
-The first immediate reason to use the group mapping on a Samba PDC, is that
-the <parameter>domain admin group</parameter> &smb.conf; has been removed.
-This parameter was used to give the listed users membership in the "Domain Admins"
-Windows group which gave local admin rights on their workstations (in
-default configurations).
-</para>
+<sect1>
+<title>Features and Benefits</title>
 
-<para>
-When installing NT/W2K on a computer, the installer program creates some users
-and groups. Notably the 'Administrators' group, and gives to that group some
-privileges like the ability to change the date and time or to kill any process
-(or close too) running on the local machine. The 'Administrator' user is a
-member of the 'Administrators' group, and thus 'inherit' the 'Administrators'
-group privileges. If a 'joe' user is created and become a member of the
-'Administrator' group, 'joe' has exactly the same rights as 'Administrator'.
-</para>
+	<para>
+	Samba allows the administrator to create MS Windows NT4 / 200x group accounts and to
+	arbitrarily associate them with Unix/Linux group accounts.
+	</para>
 
-<para>
-When a NT/W2K machine is joined to a domain, the "Domain Adminis" group of the
-PDC is added to the local 'Administrators' group of the workstation. Every
-member of the 'Domain Administrators' group 'inherit' the
-rights of the local 'Administrators' group when logging on the workstation.
+	<para>
+	Group accounts can be managed using the MS Windows NT4 or MS Windows 200x MMC tools
+	so long as appropriate interface scripts have been provided to &smb.conf;.
+	</para>
+
+	<para>
+	Administrators should be aware that where &smb.conf; group interface scripts make
+	direct calls to the Unix/Linux system tools (eg: the shadow utilities, <command>groupadd</command>,
+	<command>groupdel</command>, <command>groupmod</command>) then the resulting Unix/Linux group names will be subject
+	to any limits imposed by these tools. If the tool does NOT allow upper case characters
+	or space characters, then the creation of an MS Windows NT4 / 200x style group of
+	<parameter>Engineering Managers</parameter> will attempt to create an identically named
+	Unix/Linux group, an attempt that will of course fail!
+	</para>
+
+	<para>
+	There are several possible work-arounds for the operating system tools limitation. One
+	method is to use a script that generates a name for the Unix/Linux system group that
+	fits the operating system limits, and that then just passes the Unix/Linux group id (GID)
+	back to the calling Samba interface. This will provide a dynamic work-around solution.
+	</para>
+
+	<para>
+	Another work-around is to manually create a Unix/Linux group, then manually create the
+	MS Windows NT4 / 200x group on the Samba server and then use the <command>net groupmap</command>
+	tool to connect the two to each other.
+	</para>
+
+</sect1>
+
+<sect1>
+<title>Discussion</title>
+
+	<para>
+	When installing <application>MS Windows NT4 / 200x</application> on a computer, the installation
+	program creates default users and groups, notably the <constant>Administrators</constant> group,
+	and gives that group privileges necessary privileges to perform essential system tasks.
+	eg: Ability to change the date and time or to kill (or close) any process running on the
+	local machine.
+	</para>
+	
+	<para>
+	The 'Administrator' user is a member of the 'Administrators' group, and thus inherits
+	'Administrators' group privileges. If a 'joe' user is created to be a member of the
+	'Administrator' group, 'joe' has exactly the same rights as 'Administrator'.
+	</para>
+
+	<para>
+	When an MS Windows NT4 / W200x is made a domain member, the "Domain Admins" group of the
+	PDC is added to the local 'Administrators' group of the workstation. Every member of the
+	'Domain Administrators' group inherits the rights of the local 'Administrators' group when
+	logging on the workstation.
+	</para>
+
+	<para>
+	The following steps describe how to make Samba PDC users members of the 'Domain Admins' group?
+	</para>
+
+	<orderedlist>
+		<listitem><para>
+		create a unix group (usually in <filename>/etc/group</filename>), let's call it domadm
+		</para></listitem>
+
+		<listitem><para>add to this group the users that must be Administrators. For example
+		if you want joe, john and mary, your entry in <filename>/etc/group</filename> will
+		look like:
+		</para>
+
+		<para><programlisting>
+		domadm:x:502:joe,john,mary
+		</programlisting>
+		</para></listitem>
+
+		<listitem><para>
+		Map this domadm group to the "Domain Admins" group by running the command:
+		</para>
+
+		<para>
+		<screen>
+		&rootprompt;<userinput>net groupmap add ntgroup="Domain Admins" unixgroup=domadm</userinput>
+		</screen>
+		</para>
+		
+		<para>
+		The quotes around "Domain Admins" are necessary due to the space in the group name.
+		Also make sure to leave no whitespace surrounding the equal character (=).
+		</para></listitem>
+	</orderedlist>
+
+	<para>
+	Now joe, john and mary are domain administrators!
+	</para>
+
+	<para>
+	It is possible to map any arbitrary UNIX group to any Windows NT4 / 200x group as well as
+	making any UNIX group a Windows domain group.  For example, if you wanted to include a
+	UNIX group (e.g. acct) in a ACL on a local file or printer on a domain member machine,
+	you would flag that group as a domain group by running the following on the Samba PDC:
+	</para>
+
+	<para>
+	<screen>
+	&rootprompt;<userinput>net groupmap add rid=1000 ntgroup="Accounting" unixgroup=acct</userinput>
+	</screen>
+	</para>
+
+	<para>
+	Be aware that the RID parameter is a unsigned 32 bit integer that should
+	normally start at 1000.  However, this rid must not overlap with any RID assigned
+	to a user.  Verifying this is done differently depending on on the passdb backend 
+	you are using.  Future versions of the tools may perform the verification automatically,
+	but for now the burden is on you.
+	</para>
+
+	<sect2>
+	<title>Example Configuration</title>
+
+		<para>
+		You can list the various groups in the mapping database by executing 
+		<command>net groupmap list</command>.  Here is an example:
+		</para>
+
+		<para>
+		<screen>
+		&rootprompt; <userinput>net groupmap list</userinput>
+		System Administrators (S-1-5-21-2547222302-1596225915-2414751004-1002) -> sysadmin
+		Domain Admins (S-1-5-21-2547222302-1596225915-2414751004-512) -> domadmin
+		Domain Users (S-1-5-21-2547222302-1596225915-2414751004-513) -> domuser
+		Domain Guests (S-1-5-21-2547222302-1596225915-2414751004-514) -> domguest
+		</screen>
+		</para>
+
+		<para>
+		For complete details on <command>net groupmap</command>, refer to the net(8) man page.
+		</para>
+
+	</sect2>
+
+</sect1>
+
+<sect1>
+<title>Configuration Scripts</title>
+
+	<para>
+	Everyone needs tools. Some of us like to create our own, others prefer to use canned tools
+	(ie: prepared by someone else for general use). 
+	</para>
+
+	<sect2>
+	<title>Sample &smb.conf; add group script</title>
+
+		<para>
+		A script to great complying group names for use by the Samba group interfaces:
+		</para>
+
+		<para>
+<example>
+	<title>smbgrpadd.sh</title>
+<programlisting>
+
+#!/bin/bash
+
+# Add the group using normal system groupadd tool.
+groupadd smbtmpgrp00
+
+thegid=`cat /etc/group | grep smbtmpgrp00 | cut -d ":" -f3`
+
+# Now change the name to what we want for the MS Windows networking end
+cp /etc/group /etc/group.bak
+cat /etc/group.bak | sed s/smbtmpgrp00/$1/g > /etc/group
+
+# Now return the GID as would normally happen.
+echo $thegid
+exit 0
+</programlisting>
+</example>
 </para>
 
+		<para>
+		The &smb.conf; entry for the above script would look like:
+		<programlisting>
+		add group script = /path_to_tool/smbgrpadd.sh %g
+		</programlisting>
+		</para>
+
+	</sect2>
+	
+	<sect2>
+	<title>Script to configure Group Mapping</title>
+
+	<para>
+	In our example we have created a Unix/Linux group called <parameter>ntadmin</parameter>.
+	Our script will create the additional groups <parameter>Engineers, Marketoids, Gnomes</parameter>:
+	</para>
+
 <para>
-The following steps describe how to make samba PDC users members of the
-'Domain Admins' group?
-</para>
+<programlisting>
+#!/bin/bash
 
-<orderedlist>
-<listitem><para>create a unix group (usually in <filename>/etc/group</filename>),
-  let's call it domadm</para></listitem>
-<listitem><para>add to this group the users that must be Administrators. For example
-  if you want joe,john and mary, your entry in <filename>/etc/group</filename> will
-  look like:</para>
+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 modify ntgroup="Administrators" unixgroup=root
+net groupmap modify ntgroup="Users" unixgroup=users
+net groupmap modify ntgroup="Guests" unixgroup=nobody
+net groupmap modify ntgroup="System Operators" unixgroup=sys
+net groupmap modify ntgroup="Account Operators" unixgroup=root
+net groupmap modify ntgroup="Backup Operators" unixgroup=bin
+net groupmap modify ntgroup="Print Operators" unixgroup=lp
+net groupmap modify ntgroup="Replicators" unixgroup=daemon
+net groupmap modify ntgroup="Power Users" unixgroup=sys
 
-  <para><programlisting>
-  domadm:x:502:joe,john,mary
-  </programlisting></para>
+#groupadd Engineers
+#groupadd Marketoids
+#groupadd Gnomes
 
-  </listitem>
+#net groupmap add ntgroup="Engineers"  unixgroup=Engineers    type=d
+#net groupmap add ntgroup="Marketoids" unixgroup=Marketoids   type=d
+#net groupmap add ntgroup="Gnomes"     unixgroup=Gnomes       type=d
+</programlisting>
+</para>
 
-<listitem><para>Map this domadm group to the "Domain Admins" group
-  by running the command:</para>
+	<para>
+	Of course it is expected that the administrator will modify this to suit local needs.
+	For information regarding the use of the <command>net groupmap</command> tool please
+	refer to the man page.
+	</para>
 
-  <para><prompt>root# </prompt><userinput>net groupmap add ntgroup="Domain Admins" unixgroup=domadm</userinput></para>
-  
-  <para>The quotes around "Domain Admins" are necessary due to the space in the group name.  Also make
-  sure to leave no whitespace surrounding the equal character (=).</para>
-  </listitem>
+	</sect2>
 
-</orderedlist>
+</sect1>
 
-<para>Now joe, john and mary are domain administrators!</para>
+<sect1>
+<title>Common Errors</title>
 
 <para>
-It is possible to map any arbitrary UNIX group to any Windows NT
-group as well as making any UNIX group a Windows domain group.
-For example, if you wanted to include a UNIX group (e.g. acct) in a ACL on a
-local file or printer on a domain member machine, you would flag
-that group as a domain group by running the following on the Samba PDC:
+At this time there are many little surprises for the unwary administrator. In a real sense
+it is imperative that every step of automated control scripts must be carefully tested
+manually before putting them into active service.
 </para>
 
-<para><prompt>root# </prompt><userinput>net groupmap add rid=1000 ntgroup="Accounting" unixgroup=acct</userinput></para>
+	<sect2>
+	<title>Adding Groups Fails</title>
+
+		<para>
+		This is a common problem when the <command>groupadd</command> is called directly
+		by the Samba interface script for the <parameter>add group script</parameter> in
+		the &smb.conf; file.
+		</para>
+
+		<para>
+		The most common cause of failure is an attempt to add an MS Windows group account
+		that has either an upper case character and/or a space character in it.
+		</para>
+
+		<para>
+		There are three possible work-arounds. Firstly, use only group names that comply
+		with the limitations of the Unix/Linux <command>groupadd</command> system tool.
+		The second involves use of the script mentioned earlier in this chapter, and the
+		third option is to manually create a Unix/Linux group account that can substitute
+		for the MS Windows group name, then use the procedure listed above to map that group
+		to the MS Windows group.
+		</para>
+
+	</sect2>
 
-<para>Be aware that the rid parmeter is a unsigned 32 bit integer that should
-normally start at 1000.  However, this rid must not overlap with any RID assigned
-to a user.  Verifying this is done differently depending on on the passdb backend 
-you are using.  Future versions of the tools may perform the verification automatically,
-but for now the burden in on you.</para>
+	<sect2>
+	<title>Adding MS Windows Groups to MS Windows Groups Fails</title>
 
-<para>You can list the various groups in the mapping database by executing 
-<command>net groupmap list</command>.  Here is an example:</para>
+		<para>
+		Samba-3 does NOT support nested groups from the MS Windows control environment.
+		</para>
 
-<para><programlisting><prompt>root# </prompt>net groupmap list
-System Administrators (S-1-5-21-2547222302-1596225915-2414751004-1002) -> sysadmin
-Domain Admins (S-1-5-21-2547222302-1596225915-2414751004-512) -> domadmin
-Domain Users (S-1-5-21-2547222302-1596225915-2414751004-513) -> domuser
-Domain Guests (S-1-5-21-2547222302-1596225915-2414751004-514) -> domguest
-</programlisting></para>
+	</sect2>
 
-<para>For complete details on <command>net groupmap</command>, refer to the 
-net(8) man page.</para>
+</sect1>
 
 </chapter>