diff options
Diffstat (limited to 'docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml')
| -rw-r--r-- | docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml | 625 |
1 files changed, 625 insertions, 0 deletions
diff --git a/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml b/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml new file mode 100644 index 0000000000..9e9d1a0e01 --- /dev/null +++ b/docs/docbook/projdoc/GROUP-MAPPING-HOWTO.xml @@ -0,0 +1,625 @@ +<?xml version="1.0" encoding="iso8859-1"?> +<chapter id="groupmapping"> +<chapterinfo> + &author.jht; + <author> + <firstname>Jean François</firstname><surname>Micouleau</surname> + </author> + &author.jerry; +</chapterinfo> +<title>Group Mapping &smbmdash; MS Windows and UNIX</title> + + + <para> +<indexterm significance="preferred"><primary>groups</primary><secondary>mapping</secondary></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 + included with the &net; tool can be used to manage these associations. + </para> + + <para> + The new facility for mapping NT Groups to UNIX system groups allows the administrator to decide + which NT Domain Groups are to be exposed to MS Windows clients. Only those NT Groups that map + to a UNIX group that has a value other than the default (<constant>-1</constant>) will be exposed + in group selection lists in tools that access domain users and groups. + </para> + + <warning> + <para> + <indexterm><primary>domain admin group</primary></indexterm> + The <parameter>domain admin group</parameter> parameter has been removed in Samba-3 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> + +<sect1> +<title>Features and Benefits</title> + + <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> +<indexterm><primary>UID</primary></indexterm> +<indexterm><primary>GID</primary></indexterm> + Group accounts can be managed using the MS Windows NT4 or MS Windows 200x/XP Professional MMC tools. + Appropriate interface scripts should be provided in &smb.conf; if it is desired that UNIX/Linux system + accounts should be automatically created when these tools are used. In the absence of these scripts, and + so long as <command>winbindd</command> is running, Samba group accounts that are created using these + tools will be allocated UNIX UIDs/GIDs from the ID range specified by the + <smbconfoption><name>idmap uid</name></smbconfoption>/<smbconfoption><name>idmap gid</name></smbconfoption> + parameters in the &smb.conf; file. + </para> + + <figure id="idmap-sid2gid"><title>IDMAP: group SID to GID resolution.</title> + <mediaobject> + <imageobject role="latex"><imagedata fileref="projdoc/imagefiles/idmap-sid2gid" scale="50" scalefit="1"/></imageobject> + <imageobject><imagedata fileref="projdoc/imagefiles/idmap-sid2gid.png" scale="50" scalefit="1"/></imageobject> + </mediaobject> + </figure> + + <figure id="idmap-gid2sid"><title>IDMAP: GID resolution to matching SID.</title> + <mediaobject> + <imageobject role="latex"><imagedata fileref="projdoc/imagefiles/idmap-gid2sid" scale="50" scalefit="1"/></imageobject> + <imageobject><imagedata fileref="projdoc/imagefiles/idmap-gid2sid.png" scale="50" scalefit="1"/></imageobject> + </mediaobject> + </figure> + + <para> + In both cases, when winbindd is not running, only locally resolvable groups can be recognized. Please refer to + <link linkend="idmap-sid2gid"></link> and <link linkend="idmap-gid2sid"></link>. The <command>net groupmap</command> is + used to establish UNIX group to NT SID mappings as shown in <link linkend="idmap-store-gid2sid"></link>. + </para> + + <figure id="idmap-store-gid2sid"><title>IDMAP storing group mappings.</title> + <mediaobject> + <imageobject role="latex"><imagedata fileref="projdoc/imagefiles/idmap-store-gid2sid" scale="50" scalefit="1"/></imageobject> + <imageobject><imagedata fileref="projdoc/imagefiles/idmap-store-gid2sid.png" scale="50" scalefit="1"/></imageobject> + </mediaobject> + </figure> + + + <para> + <indexterm><primary>groupadd</primary></indexterm> + <indexterm><primary>groupdel</primary></indexterm> + Administrators should be aware that where &smb.conf; group interface scripts make + direct calls to the UNIX/Linux system tools (the shadow utilities, <command>groupadd</command>, + <command>groupdel</command>, and <command>groupmod</command>), 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 + <ntgroup>Engineering Managers</ntgroup> will attempt to create an identically named + UNIX/Linux group, an attempt that will of course fail. + </para> + + + + <para> + <indexterm><primary>GID</primary></indexterm> + <indexterm><primary>SID</primary></indexterm> + 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, + such as the ability to change the date and time or to kill (or close) any process running on the + local machine. + </para> + + <para> + <indexterm><primary>Administrator</primary></indexterm> + The <constant>Administrator</constant> user is a member of the <constant>Administrators</constant> group, and thus inherits + <constant>Administrators</constant> group privileges. If a <constant>joe</constant> user is created to be a member of the + <constant>Administrators</constant> group, <constant>joe</constant> has exactly the same rights as the user, + <constant>Administrator</constant>. + </para> + + <para> + When an MS Windows NT4/200x/XP machine is made a Domain Member, the <quote>Domain Admins</quote> group of the + PDC is added to the local <constant>Administrators</constant> group of the workstation. Every member of the + <constant>Domain Administrators</constant> group inherits the rights of the local <constant>Administrators</constant> group when + logging on the workstation. + </para> + + <para> + The following steps describe how to make Samba PDC users members of the <constant>Domain Admins</constant> group? + </para> + + <orderedlist> + <listitem><para> + Create a UNIX group (usually in <filename>/etc/group</filename>), let's call it <constant>domadm</constant>. + </para></listitem> + + <listitem><para> + Add to this group the users that must be <quote>Administrators</quote>. For example, + if you want <constant>joe, john</constant> and <constant>mary</constant> to be administrators, + your entry in <filename>/etc/group</filename> will look like this: + </para> + + <para><programlisting> + domadm:x:502:joe,john,mary + </programlisting> + </para></listitem> + + <listitem><para> + Map this domadm group to the <quote>Domain Admins</quote> group by running the command: + </para> + + <para> + <screen> + &rootprompt;<userinput>net groupmap add ntgroup="Domain Admins" UNIXgroup=domadm</userinput> + </screen> + </para> + + <para> + <indexterm><primary>Domain Admins group</primary></indexterm> + The quotes around <quote>Domain Admins</quote> are necessary due to the space in the group name. + Also make sure to leave no white-space surrounding the equal character (=). + </para></listitem> + </orderedlist> + + <para> + Now <constant>joe, john</constant> and <constant>mary</constant> are domain administrators. + </para> + + <para> + <indexterm><primary>groups</primary><secondary>domain</secondary></indexterm> + 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 an 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. Verification for this is done differently depending 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>Default Users, Groups and Relative Identifiers</title> + + <para> +<indexterm><primary>Relative Identifier</primary><see>RID</see></indexterm> +<indexterm><primary>RID</primary></indexterm> + When first installed, Microsoft Windows NT4/200x/XP are preconfigured with certain User, Group, and + Alias entities. Each has a well-known Relative Identifier (RID). These must be preserved for continued + integrity of operation. Samba must be provisioned with certain essential Domain Groups that require + the appropriate RID value. When Samba-3 is configured to use <constant>tdbsam</constant> the essential + Domain Groups are automatically created. It is the LDAP administrators' responsibility to create + (provision) the default NT Groups. + </para> + + <para> + Each essential Domain Group must be assigned its respective well-kown RID. The default Users, Groups, + Aliases, and RIDs are shown in <link linkend="WKURIDS"/>. + </para> + + <note><para> + When the <parameter>passdb backend</parameter> uses LDAP (<constant>ldapsam</constant>) it is the + admininstrators' responsibility to create the essential Domain Groups, and to assign each its default RID. + </para></note> + + <para> + It is permissible to create any Domain Group that may be necessary, just make certain that the essential + Domain Groups (well known) have been created and assigned its default RID. Other groups you create may + be assigned any arbitrary RID you care to use. + </para> + + <para> + Be sure to map each Domain Group to a UNIX system group. That is the only way to ensure that the group + will be available for use as an NT Domain Group. + </para> + + <para> + <table frame="all" id="WKURIDS"> + <title>Well-Known User Default RIDs</title> + <tgroup cols="4" align="left"> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="left"/> + <colspec align="center"/> + <thead> + <row> + <entry>Well-Known Entity</entry> + <entry>RID</entry> + <entry>Type</entry> + <entry>Essential</entry> + </row> + </thead> + <tbody> + <row> + <entry>Domain Administrator</entry> + <entry>500</entry> + <entry>User</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Guest</entry> + <entry>501</entry> + <entry>User</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain KRBTGT</entry> + <entry>502</entry> + <entry>User</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Admins</entry> + <entry>512</entry> + <entry>Group</entry> + <entry>Yes</entry> + </row> + <row> + <entry>Domain Users</entry> + <entry>513</entry> + <entry>Group</entry> + <entry>Yes</entry> + </row> + <row> + <entry>Domain Guests</entry> + <entry>514</entry> + <entry>Group</entry> + <entry>Yes</entry> + </row> + <row> + <entry>Domain Computers</entry> + <entry>515</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Controllers</entry> + <entry>516</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Certificate Admins</entry> + <entry>517</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Schema Admins</entry> + <entry>518</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Enterprise Admins</entry> + <entry>519</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Domain Policy Admins</entry> + <entry>520</entry> + <entry>Group</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Admins</entry> + <entry>544</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin users</entry> + <entry>545</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Guests</entry> + <entry>546</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Power Users</entry> + <entry>547</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Account Operators</entry> + <entry>548</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin System Operators</entry> + <entry>549</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Print Operators</entry> + <entry>550</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Backup Operators</entry> + <entry>551</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin Replicator</entry> + <entry>552</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + <row> + <entry>Builtin RAS Servers</entry> + <entry>553</entry> + <entry>Alias</entry> + <entry>No</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + + </sect2> + + <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> + +<indexterm><primary>net</primary><secondary>groupmap</secondary></indexterm> + + <para> +<screen> +&rootprompt; <userinput>net groupmap list</userinput> +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 + (i.e., prepared by someone else for general use). + </para> + + <sect2> + <title>Sample &smb.conf; Add Group Script</title> + + <para> + A script to create complying group names for use by the Samba group interfaces + is provided in <link linkend="smbgrpadd.sh"></link>. + </para> + +<indexterm><primary>smbgrpadd.sh</primary></indexterm> + <para> +<example id="smbgrpadd.sh"> + <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 be something like that in <link linkend="smbgrpadd"/>. +<smbconfexample id="smbgrpadd"> +<title>Configuration of &smb.conf; for the add group script.</title> +<smbconfsection>[global]</smbconfsection> +<member>...</member> +<smbconfoption><name>add group script</name><value>/path_to_tool/smbgrpadd.sh %g</value></smbconfoption> +<member>...</member> +</smbconfexample> + </para> + + </sect2> + + <sect2> + <title>Script to Configure Group Mapping</title> + + <para> + In our example we have created a UNIX/Linux group called <ntgroup>ntadmin</ntgroup>. + Our script will create the additional groups <ntgroup>Orks</ntgroup>, <ntgroup>Elves</ntgroup>, and <ntgroup>Gnomes</ntgroup>. + It is a good idea to save this shell script for later re-use just in case you ever need to rebuild your mapping database. + For the sake of concenience we elect to save this script as a file called <filename>initGroups.sh</filename>. + This script is given in <link linkend="set-group-map"></link>. + </para> + +<para> +<indexterm><primary>initGroups.sh</primary></indexterm> +<example id="set-group-map"> + <title>Script to Set Group Mapping</title> +<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 + +groupadd Orks +groupadd Elves +groupadd Gnomes + +net groupmap add ntgroup="Orks" unixgroup=Orks type=d +net groupmap add ntgroup="Elves" unixgroup=Elves type=d +net groupmap add ntgroup="Gnomes" unixgroup=Gnomes type=d +</programlisting> +</example> +</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> + + </sect2> + +</sect1> + +<sect1> +<title>Common Errors</title> + +<para> +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> + + <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 <smbconfoption><name>add group script</name></smbconfoption> 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. First, use only group names that comply + with the limitations of the UNIX/Linux <command>groupadd</command> system tool. + Second, it involves the use of the script mentioned earlier in this chapter, and + third is the 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> + + <sect2> + <title>Adding MS Windows Groups to MS Windows Groups Fails</title> + + <indexterm><primary>groups</primary><secondary>nested</secondary></indexterm> + + <para> + Samba-3 does not support nested groups from the MS Windows control environment. + </para> + + </sect2> + + <sect2> + <title>Adding <emphasis>Domain Users</emphasis> to the <emphasis>Power Users</emphasis> Group</title> + + <para><quote> + What must I do to add Domain Users to the Power Users group? + </quote></para> + +<indexterm><primary>Domain Users group</primary></indexterm> + + <para> + The Power Users group is a group that is local to each Windows 200x/XP Professional workstation. + You cannot add the Domain Users group to the Power Users group automatically, it must be done on + each workstation by logging in as the local workstation <emphasis>administrator</emphasis> and + then using the following procedure: + </para> + + <procedure> + <step><para> + Click <guimenu>Start -> Control Panel -> Users and Passwords</guimenu>. + </para></step> + + <step><para> + Click the <guimenuitem>Advanced</guimenuitem> tab. + </para></step> + + <step><para> + Click the <guibutton>Advanced</guibutton> button. + </para></step> + + <step><para> + Click <constant>Groups</constant>. + </para></step> + + <step><para> + Double click <constant>Power Users</constant>. This will launch the panel to add users or groups + to the local machine <constant>Power Uses</constant> group. + </para></step> + + <step><para> + Click the <guibutton>Add</guibutton> button. + </para></step> + + <step><para> + Select the domain from which the <constant>Domain Users</constant> group is to be added. + </para></step> + + <step><para> + Double click the <constant>Domain Users</constant> group. + </para></step> + + <step><para> + Click the <guibutton>Ok</guibutton> button. If a logon box is presented during this process + please remember to enter the connect as <constant>DOMAIN\UserName</constant>. i.e., For the + domain <constant>MIDEARTH</constant> and the user <constant>root</constant> enter + <constant>MIDEARTH\root</constant>. + </para></step> + </procedure> + </sect2> + +</sect1> + +</chapter> |