summaryrefslogtreecommitdiff
path: root/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml')
-rw-r--r--docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml351
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>