Difference between revisions of "Idmap config ad"

m (Reverted edits by Hortimech (talk) to last revision by Mmuehlfeld)
(Rewrote page. Clearer structure, removed a lot of duplicate content, refreshed examples, added admonitions,)
Line 1: Line 1:
 
= Introduction =
 
= Introduction =
  
The "idmap_ad" module implements a read-only API to retrieve information from Active Directory. It can be used in two ways:
+
The <code>ad</code> ID mapping back end implements a read-only API to read account and group information from Active Directory (AD). The back end is based on RFC 2307. For further details, see https://www.rfc-editor.org/rfc/rfc2307.txt.
  
* '''winbind nss info = rfc2307'''
+
Alternatives to the <code>rid</code> back end:
:Retrieve individual settings for users (UID, Login Shell, Home Directory, Primary Group) and groups (GID) from AD
+
* [[Idmap_config_rid|idmap config rid]]
:* <u>Advantages:</u>
+
* [[Idmap_config_autorid|idmap config autorid]]
::* Central administration of IDs inside Active Directory
 
::* Consistent IDs on all Domain Members that use idmap_ad
 
::* Fast setting of attributes: Groups only need a GID assigned, new users UID, NIS domain, login shell, home directory and primary group
 
::* Central management removes the necessity for local ID mappings that may lead to file ownership lose, if the local database corrupts.
 
::* Individual login shells and home directory paths for users
 
::* Login shell and home directory settings are the same on all Domain Members using idmap_ad with winbind nss info = rfc2307
 
::* Easy [[Maintaining_Unix_Attributes_in_AD_using_ADUC|user/group management using Active Directory Users and Computers (ADUC)]], which is part of [[Installing RSAT|RSAT]].
 
::* No manual counting of ID values is required to avoid duplicated if using ADUC
 
:* <u>Disadvantages:</u>
 
::* If not using ADUC, manual counting of ID values is required to avoid duplicates
 
::* RFC2307 values need to be set once in AD for each user/group
 
  
  
* '''winbind nss info = template'''
 
:Retrieve just UID and GID values from AD and set the values for login shell and home directory to a common setting for all users on that host
 
:* <u>Advantages:</u>
 
::* Central administration of IDs inside Active Directory
 
::* Consistent IDs on all Domain Members that use idmap_ad
 
::* Fast setting of attributes: Users/groups only need a UID/GID assigned in AD
 
::* Central management removes the necessity for local ID mappings that may lead to file ownership lose, if the local database corrupts
 
:* <u>Disadvantages:</u>
 
::* All users have the same login shell (e. g. /bin/bash or /sbin/nologin) and home directory base path (e. g. /home/...)
 
::* Manual counting of ID values is required to avoid duplicates
 
::* UID/GID values need to be set once in AD for each user/group
 
  
  
For both configurations, [https://www.rfc-editor.org/rfc/rfc2307.txt RFC2307] is relevant. It describes the possibility to store e. g. user and group information in an LDAP directory to allow central administration with several advantages (see above).
 
  
 +
= Advantages and Disadvantages of the <code>ad</code> Back End =
  
 +
Advantages:
 +
* Central administration of IDs inside Active Directory (AD).
 +
* Consistent IDs on all Samba clients and servers using the <code>ad</code> back end.
 +
* Attributes need to be set only once when the user or group is created.
 +
* IDs are not stored in a local database that can corrupt and thus file ownerships are not lost.
  
 +
Disadvantages:
 +
* If not using the Windows <code>Active Directory Users and Computers</code> (ADUC) program, you have to manual track ID values to avoid duplicates.
 +
* RFC2307 values must be set manually.
  
 +
<code>winbind NSS info</code> mode-specific features:
 +
* <code>rfc2307</code>: Individual login shells and home directory paths for users.
 +
* <code>template</code>: Same login shells and home directory base paths for users.
  
= winbind nss info = rfc2307 =
 
  
== Prerequisites ==
 
  
* [[Setting_up_RFC2307_in_AD#Verifying_the_Domain_Controller_and_Active_Directory_Setup|RFC2307 enabled]] in each DCs smb.conf
 
* '''Users have the uidNumber attribute set in AD'''
 
:* Any users that you want to be visible on a Unix domain member must have a uidNumber attribute containing a unique number inside the range set in smb.conf
 
::i.e. '10000-99999' as shown in the example below.
 
* '''Groups have the gidNumber attribute set in AD''' (at least the users primary group, usually Domain Users)
 
:* You '''must''' set a gidNumber attribute on Domain Users, it must contain a number inside the range set in smb.conf.
 
* Optional: [[Setting_up_RFC2307_in_AD#Check_if_NIS_Extensions_are_installed_in_your_Directory|NIS extensions]]. Only required for ADUC, e. g. to track the last assigned uidNumber. If the ADUC console is not used, the NIS extensions are not required.
 
  
  
 +
= Planning the ID Ranges =
  
== smb.conf settings ==
+
Before configuring the <code>ad</code> back end in the <code>smb.conf</code> file, select unique ID ranges Samba can use for each domain. The ranges must be continuous and big enough to enable Samba to assign an ID for every future user and group created in the domain.
  
Add the following to the [global] section of your smb.conf:
+
{{Imbox
 +
| type = important
 +
| text = The ID ranges of the <code>*</code> default domain and all other domains configured in the <code>smb.conf</code> file must not overlap.
 +
}}
  
[global]
 
        ...
 
        # '''Do not use these lines on a DC, they will do NOTHING!'''
 
                                                                   
 
        # '''Important: The ranges of the default (*) idmap config'''
 
        # '''and the domain(s) <u>must not</u> overlap!'''
 
                                                                       
 
        # Default idmap config used for BUILTIN and local windows accounts/groups
 
        idmap config *:backend = tdb
 
        idmap config *:range = 2000-9999
 
 
        # idmap config for domain SAMDOM
 
        idmap config SAMDOM:backend = ad
 
        idmap config SAMDOM:schema_mode = rfc2307
 
        idmap config SAMDOM:range = 10000-99999
 
 
        # Use settings from AD for login shell and home directory
 
        winbind nss info = rfc2307
 
  
See the manpage of smb.conf and idmap_ad for information about the parameters and options used. The range of the domain idmap config defines the lowest to the highest UID/GID that will ever be used in this domain. If you have any higher or lower IDs, they won't be retrieved! Ask your AD Administrator if unsure which range to set.
 
  
  
  
 +
= Prerequisites =
  
 +
To enable Samba to retrieve user and group information from Active Directory (AD):
  
= winbind nss info = template =
+
* Users must have at least the <code>uidNumber</code> and groups the <code>gidNumber</code> attribute set. When using the <code>rfc2307</code> <code>winbind NSS info</code> mode, user accounts must have additionally the <code>loginShell</code>, <code>unixHomeDirectory</code> and <code>primaryGroupID</code> set.
 +
* The user and group IDs must be within the range configured in the <code>smb.conf</code> for this domain.
 +
* If the <code>Active Directory Users and Groups</code> (ADUC) utility is used to assign the UNIX attributes, the NIS extensions have to be installed. For details, see [[Setting_up_RFC2307_in_AD|Setting up RFC2307 in AD]].
 +
* User IDs must be unique for all users and group IDs for all groups. Duplicate IDs or reusing IDs of previously deleted accounts enable the new user or group to access files created by the previous ID owner. When using the ADUC utility, the IDs are automatically tracked inside AD and incremented when creating a new user or group.
 +
* The primary user group of user accounts, this is typically the <code>Domain Users</code> group, must have a <code>gidNumber</code> attribute set. If the attribute is not set for the primary group, the users are not visible on the machine having the <code>ad</code> ID mapping back end configured.
  
== Prerequisites ==
 
  
* '''Users have the uidNumber attribute set in AD'''
 
:* Any users that you want to be visible on a Unix domain member must have a uidNumber attribute containing a unique number inside the range set in smb.conf
 
::i.e. '10000-99999' as shown in the example below.
 
* '''Groups have the gidNumber attribute set in AD''' (at least the users primary group, usually Domain Users)
 
:* You '''must''' set a gidNumber attribute on Domain Users, it must contain a number inside the range set in smb.conf.
 
  
  
<u>Additional information:</u>
 
  
The uidNumber and gidNumber attributes are part of the Samba AD schema. There's no need to have the [[Setting_up_RFC2307_in_AD#Check_if_NIS_Extensions_are_installed_in_your_Directory|NIS extensions]] installed. Anyway there are a few things to mention:
+
= The <code>RFC2307</code> and <code>template</code> <code>winbind NSS info mode</code> options =
  
* IDs have to be incremented manually and it's the AD administrators responsibility to avoid duplicates or reusing IDs. User/groups having the same IDs as existing or alumni ones, will own and have access to the same files/directories!
+
The <code>ad</code> ID mapping back end supports two modes, set in the <code>winbind nss info</code> parameter in the <code>[global]</code> section of the <code>smb.conf</code> file:
* You can't use the "UNIX attributes" tab in ADUC, if [[Setting_up_RFC2307_in_AD#Check_if_NIS_Extensions_are_installed_in_your_Directory|NIS extensions]] aren't installed. You need to assign the IDs using the attributes listing in the identically named tab of ADUC, using samba-tool during user creation or afterwards using ldbedit.
 
  
 +
* <code>winbind nss info = rfc2307</code>: All information are read from Active Directory (AD):
 +
:* Users: Account name, UID, login shell, home directory path, and primary group.
 +
:* Groups: Group name and GID.
  
 +
* <code>winbind nss info = template</code>: Only the following values are read from AD:
 +
:* Users: Account name, UID, and primary group.
 +
:: The login shell and home directory is automatically set by user-indepentend settings in the <code>smb.conf</code> file.
 +
:* Groups: Group name and GUID
  
== smb.conf settings ==
 
  
Add the following to the [global] section of your smb.conf:
 
  
[global]
 
        ...
 
        # '''Do not use these lines on a DC, they will do NOTHING!'''
 
                                                                     
 
        # '''Important: The ranges of the default (*) idmap config'''
 
        # '''and the domain(s) <u>must not</u> overlap!'''
 
                                                                                                                             
 
        # Default idmap config used for BUILTIN and local accounts/groups
 
        idmap config *:backend = tdb
 
        idmap config *:range = 2000-9999
 
 
        # idmap config for domain SAMDOM
 
        idmap config SAMDOM:backend = ad
 
        idmap config SAMDOM:schema_mode = rfc2307
 
        idmap config SAMDOM:range = 10000-99999
 
 
        # Use template settings for login shell and home directory
 
        winbind nss info = template
 
        template shell = /sbin/nologin
 
        template homedir = /home/%U
 
  
See the manpage of smb.conf and idmap_ad for information about the parameters and options used. The range of the domain idmap config defines the lowest to the highest UID/GID that will ever be used in this domain. If you have any higher or lower IDs, they won't be retrieved! Ask your AD Administrator if unsure which range to set.
+
= Configuring the <code>ad</code> Back End =
  
 +
* Set the following in the <code>[global]</code> section of your <code>smb.conf</code> file:
  
 +
:* If no back end for local <code>BUILTIN</code> accounts and groups on the domain member is configured, add the <code>tdb</code> back end for <code>*</code> default domain and set an ID range. For example:
  
 +
# Default idmap config for local BUILTIN accounts and groups
 +
idmap config * : backend = tdb
 +
idmap config * : range = 3000-8000
  
 +
:: Setting the default back end is mandatory.
  
= Using idmap_ad on a Samba DC =
+
:* To configure the <code>ad</code> back end using the <code>10000-999999</code> ID range for the <code>SAMDOM</code> domain:
  
''Skip this section if configuring idmap_ad on a Domain Member.''
+
# idmap config for the SAMDOM domain
 +
idmap config SAMDOM:backend = ad
 +
idmap config SAMDOM:schema_mode = rfc2307
 +
idmap config SAMDOM:range = 10000-999999
  
Since Samba 4.2, Winbindd is now used on a Samba Domain Controller, instead of the Winbind built into the "samba" binary. It was decided to stop the development of the built-in Winbind, because it doesn't had the same quality and feature set as Winbindd. Users running 4.0 or 4.1 should update to 4.2 or later to use Winbindd with idmap_ad.
+
::{{Imbox
 +
| type = important
 +
| text = For every domain, set these parameters individually. The ID ranges of the <code>*</code> default domain and all other domains configured in the <code>smb.conf</code> file must not overlap.
 +
}}
  
If you upgrade your DC from an earlier version and have a "server services" line in your smb.conf, you need to replace the "winbind" entry with "winbindd":
+
* Configure the Winbind NSS info mode:
  
[global]
+
:* To enable the <code>template</code> mode and set, for example, <code>/bin/bash</code> as shell and <code>/home/%U</code> as home directory path:
        ...
 
        server services = ....., <s>winbind,</s> winbindd
 
  
If you haven’t got a "server services" line, no changes are required. The default value of the "server services" parameter is to enable Winbindd.
+
# Template settings for login shell and home directory
 +
winbind nss info = template
 +
template shell = /bin/bash
 +
template homedir = /home/%U
  
Winbindd is now automatically started as a child process by the "samba" binary on startup and should not be started manually!
+
:: The values are applied to all users in all domains having the <code>schema_mode = template</code> parameter set. Samba resolves the <code>%U</code> variable to the session user name. For details, see the <code>VARIABLE SUBSTITUTIONS</code> section in the <code>smb.conf(5)</code> man page.
 +
 
 +
:* To enable the <code>rfc2307</code> mode, set:
 +
 
 +
winbind nss info = rfc2307
 +
 
 +
* Reload Samba:
 +
 
 +
# smbcontrol all reload-config
 +
 
 +
For further details, see the <code>smb.conf(5)</code> and <code>idmap_ad(5)</code> man page.
 +
 
 +
 
 +
 
 +
 
 +
 
 +
= Using the <code>ad</code> Back End on a Samba AD Domain Controller =
 +
 
 +
Samba 4.0 and 4.1 used a new <code>Winbind</code> implementation built into the <code>samba</code> command. However, this implementation never worked correctly. For this reason, Samba 4.2 enabled the <code>winbindd</code> utility to be used on domain controllers (DC).
 +
 
 +
{{Imbox
 +
| type = note
 +
| text = If you run a Samba version prior 4.2, update to a supported version before using the <code>ad</code> back end on a Samba Active Directory (AD) DC. For details, see [[Updating_Samba|Updating Samba]].
 +
}}
 +
 
 +
To set up the <code>ad</code> ID mapping back end locally on a Samba AD DC, verify that you are not using the unsupported <code>samba</code> built-in <code>Winbind</code> implementation. If the <code>server services</code> parameter in your <code>smb.conf</code> file lists the option <code>winbind</code>, replace it with <code>winbindd</code>:
 +
server services = ..., <s>winbind,</s> <u>winbindd</u>,...
 +
 
 +
If you do not have the <code>server services</code> parameter in your <code>smb.conf</code> file or it already lists the <code>winbindd</code> option, Samba automatically starts the <code>winbindd</code> service on Samba 4.2 and later when the <code>samba</code> service is started.
 +
 
 +
To verify that the <code>winbindd</code> service is started as a subprocess of the <code>samba</code> process, enter:
  
 
  # ps axf
 
  # ps axf
 
  ...
 
  ...
  2156 ?        Ss    0:00 /usr/local/samba/sbin//samba -D
+
  2156 ?        Ss    0:00 /usr/local/samba/sbin/samba -D
...
+
  2158 ?        S      0:00  \_ /usr/local/samba/sbin/samba -D
  2158 ?        S      0:00  \_ /usr/local/samba/sbin//samba -D
 
 
  2172 ?        R      0:00      \_ /usr/local/samba/sbin/winbindd -D --option=server role check:inhibit=yes --foreground
 
  2172 ?        R      0:00      \_ /usr/local/samba/sbin/winbindd -D --option=server role check:inhibit=yes --foreground
 
  ...
 
  ...
 +
 +
{{Imbox
 +
| type = important
 +
| text = Do not start the <code>winbindd</code> service manually on a Samba AD DC.
 +
}}

Revision as of 17:30, 4 December 2016

Introduction

The ad ID mapping back end implements a read-only API to read account and group information from Active Directory (AD). The back end is based on RFC 2307. For further details, see https://www.rfc-editor.org/rfc/rfc2307.txt.

Alternatives to the rid back end:



Advantages and Disadvantages of the ad Back End

Advantages:

  • Central administration of IDs inside Active Directory (AD).
  • Consistent IDs on all Samba clients and servers using the ad back end.
  • Attributes need to be set only once when the user or group is created.
  • IDs are not stored in a local database that can corrupt and thus file ownerships are not lost.

Disadvantages:

  • If not using the Windows Active Directory Users and Computers (ADUC) program, you have to manual track ID values to avoid duplicates.
  • RFC2307 values must be set manually.

winbind NSS info mode-specific features:

  • rfc2307: Individual login shells and home directory paths for users.
  • template: Same login shells and home directory base paths for users.



Planning the ID Ranges

Before configuring the ad back end in the smb.conf file, select unique ID ranges Samba can use for each domain. The ranges must be continuous and big enough to enable Samba to assign an ID for every future user and group created in the domain.



Prerequisites

To enable Samba to retrieve user and group information from Active Directory (AD):

  • Users must have at least the uidNumber and groups the gidNumber attribute set. When using the rfc2307 winbind NSS info mode, user accounts must have additionally the loginShell, unixHomeDirectory and primaryGroupID set.
  • The user and group IDs must be within the range configured in the smb.conf for this domain.
  • If the Active Directory Users and Groups (ADUC) utility is used to assign the UNIX attributes, the NIS extensions have to be installed. For details, see Setting up RFC2307 in AD.
  • User IDs must be unique for all users and group IDs for all groups. Duplicate IDs or reusing IDs of previously deleted accounts enable the new user or group to access files created by the previous ID owner. When using the ADUC utility, the IDs are automatically tracked inside AD and incremented when creating a new user or group.
  • The primary user group of user accounts, this is typically the Domain Users group, must have a gidNumber attribute set. If the attribute is not set for the primary group, the users are not visible on the machine having the ad ID mapping back end configured.



The RFC2307 and template winbind NSS info mode options

The ad ID mapping back end supports two modes, set in the winbind nss info parameter in the [global] section of the smb.conf file:

  • winbind nss info = rfc2307: All information are read from Active Directory (AD):
  • Users: Account name, UID, login shell, home directory path, and primary group.
  • Groups: Group name and GID.
  • winbind nss info = template: Only the following values are read from AD:
  • Users: Account name, UID, and primary group.
The login shell and home directory is automatically set by user-indepentend settings in the smb.conf file.
  • Groups: Group name and GUID



Configuring the ad Back End

  • Set the following in the [global] section of your smb.conf file:
  • If no back end for local BUILTIN accounts and groups on the domain member is configured, add the tdb back end for * default domain and set an ID range. For example:
# Default idmap config for local BUILTIN accounts and groups
idmap config * : backend = tdb
idmap config * : range = 3000-8000
Setting the default back end is mandatory.
  • To configure the ad back end using the 10000-999999 ID range for the SAMDOM domain:
# idmap config for the SAMDOM domain
idmap config SAMDOM:backend = ad
idmap config SAMDOM:schema_mode = rfc2307
idmap config SAMDOM:range = 10000-999999
  • Configure the Winbind NSS info mode:
  • To enable the template mode and set, for example, /bin/bash as shell and /home/%U as home directory path:
# Template settings for login shell and home directory
winbind nss info = template
template shell = /bin/bash
template homedir = /home/%U
The values are applied to all users in all domains having the schema_mode = template parameter set. Samba resolves the %U variable to the session user name. For details, see the VARIABLE SUBSTITUTIONS section in the smb.conf(5) man page.
  • To enable the rfc2307 mode, set:
winbind nss info = rfc2307
  • Reload Samba:
# smbcontrol all reload-config

For further details, see the smb.conf(5) and idmap_ad(5) man page.



Using the ad Back End on a Samba AD Domain Controller

Samba 4.0 and 4.1 used a new Winbind implementation built into the samba command. However, this implementation never worked correctly. For this reason, Samba 4.2 enabled the winbindd utility to be used on domain controllers (DC).

To set up the ad ID mapping back end locally on a Samba AD DC, verify that you are not using the unsupported samba built-in Winbind implementation. If the server services parameter in your smb.conf file lists the option winbind, replace it with winbindd:

server services = ..., winbind, winbindd,...

If you do not have the server services parameter in your smb.conf file or it already lists the winbindd option, Samba automatically starts the winbindd service on Samba 4.2 and later when the samba service is started.

To verify that the winbindd service is started as a subprocess of the samba process, enter:

# ps axf
...
2156 ?        Ss     0:00 /usr/local/samba/sbin/samba -D
2158 ?        S      0:00  \_ /usr/local/samba/sbin/samba -D
2172 ?        R      0:00      \_ /usr/local/samba/sbin/winbindd -D --option=server role check:inhibit=yes --foreground
...