docs/Samba3-HOWTO/TOSHARG-IDMAP.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <chapter id="idmapper">
   4 <chapterinfo>
   5         &author.jht;
   6 </chapterinfo>
   7
   8 <title>Identity Mapping (IDMAP)</title>
   9
  10 <para>
  11 <indexterm><primary>Windows</primary></indexterm>
  12 <indexterm><primary>interoperability</primary></indexterm>
  13 <indexterm><primary>IDMAP</primary></indexterm>
  14 <indexterm><primary>Windows Security Identifiers</primary><see>SID</see></indexterm>
  15 <indexterm><primary>SID</primary></indexterm>
  16 <indexterm><primary>UID</primary></indexterm>
  17 <indexterm><primary>GID</primary></indexterm>
  18 The Microsoft Windows operating system has a number of features that impose specific challenges
  19 to interoperability with operating system on which Samba is implemented. This chapter deals
  20 explicitly with the mechanisms Samba-3 (version 3.0.8 and later) uses to overcome one of the
  21 key challenges in the integration of Samba servers into an MS Windows networking environment.
  22 This chapter deals with Identify Mapping (IDMAP) of Windows Security Identifers (SIDs)
  23 to UNIX UIDs and GIDs.
  24 </para>
  25
  26 <para>
  27 To ensure good sufficient coverage each possible Samba deployment type will be discussed.
  28 This is followed by an overview of how the IDMAP facility may be implemented.
  29 </para>
  30
  31 <para>
  32 <indexterm><primary>network client</primary></indexterm>
  33 The IDMAP facility is usually of concern where more than one Samba server (or Samba network client)
  34 is installed in the one Domain. Where there is a single Samba server do not be too concerned regarding
  35 the IDMAP infrastructure - the default behavior of Samba is nearly always sufficient.
  36 </para>
  37
  38 <para>
  39 <indexterm><primary>one domain</primary></indexterm>
  40 The use of IDMAP is important where the Samba server will be accessed by workstations or servers from
  41 more than one domain, in which case it is important to run winbind so it can handle the resolution (ID mapping)
  42 of foreign SIDs to local UNIX UIDs and GIDs.
  43 </para>
  44
  45 <para>
  46 <indexterm><primary>winbindd</primary></indexterm>
  47 The use of the IDMAP facility requires that the <command>winbindd</command> be executed on Samba start-up.
  48 </para>
  49
  50 <sect1>
  51 <title>Samba Server Deployment Types and IDMAP</title>
  52
  53 <para>
  54 <indexterm><primary>Server Types</primary></indexterm>
  55 There are four (4) basic server deployment types, as documented in <link linkend="ServerType">the chapter
  56 on Server Types and Security Modes</link>.
  57 </para>
  58
  59         <sect2>
  60         <title>Stand-Alone Samba Server</title>
  61
  62         <para>
  63         <indexterm><primary>stand-alone server</primary></indexterm>
  64         <indexterm><primary>Active Directory</primary></indexterm>
  65         <indexterm><primary>NT4 Domain</primary></indexterm>
  66         A stand-alone Samba server is an implementation that is not a member of a Windows NT4 Domain,
  67         a Windows 200X Active Directory Domain, or of a Samba Domain.
  68         </para>
  69
  70         <para>
  71         <indexterm><primary>IDMAP</primary></indexterm>
  72         <indexterm><primary>identity</primary></indexterm>
  73         By definition, this means that users and groups will be created and controlled locally and
  74         the identity of a network user must match a local UNIX/Linux user login. The IDMAP facility
  75         is therefore of little to no interest, winbind will not be necessary, and the IDMAP facility
  76         will not be relevant or of interest.
  77         </para>
  78
  79         </sect2>
  80
  81         <sect2>
  82         <title>Domain Member Server or Domain Member Client</title>
  83
  84         <para>
  85         <indexterm><primary>PDC</primary></indexterm>
  86         <indexterm><primary>BDC</primary></indexterm>
  87         <indexterm><primary>NT4</primary></indexterm>
  88         <indexterm><primary>SID</primary></indexterm>
  89         <indexterm><primary>Active Directory</primary></indexterm>
  90         Samba-3 can act as a Windows NT4 PDC or BDC thereby providing domain control protocols that
  91         are compatible with Windows NT4. Samba-3 file and print sharing protocols are compatible with
  92         all version of Microsoft Windows products. Windows NT4, as with Microsoft Active Directory,
  93         extensively makes use of Windows security identifiers (SIDs).
  94         </para>
  95
  96         <para>
  97         <indexterm><primary>MS Windows SID</primary></indexterm>
  98         <indexterm><primary>UID</primary></indexterm>
  99         <indexterm><primary>GID</primary></indexterm>
 100         Samba-3 Domain Member servers and clients must interact correctly with MS Windows SIDs. Incoming
 101         Windows SIDs must be translated to local UNIX UIDs and GIDs. Outgoing information from the Samba
 102         server must provide to MS Windows clients and servers appropriate SIDs.
 103         </para>
 104
 105         <para>
 106         <indexterm><primary>ADS</primary></indexterm>
 107         <indexterm><primary>winbind</primary></indexterm>
 108         A Samba member of a Windows networking domain (NT4-style or ADS) can be configured to handle
 109         identity mapping in a variety of ways. The mechanism is will use depends on whether or not
 110         the <command>winbindd</command> daemon is used, and how the winbind functionality is configured.
 111         The configuration options are briefly described here:
 112         </para>
 113
 114         <variablelist>
 115                 <varlistentry><term>Winbind is not used, users and groups are local: &smbmdash; </term>
 116                         <listitem>
 117                                 <para>
 118                                 Where <command>winbindd</command> is not used Samba (<command>smbd</command>)
 119                                 uses the underlying UNIX/Linux mechanisms to resolve the identity of incoming
 120                                 network traffic. This will be done using the LoginID (account name) in the
 121                                 session setup request and passing it to the getpwnam() system function call.
 122                                 This call is implemented using the name service switch (NSS) mechanism on
 123                                 modern UNIX/Linux systems. By saying <quote>users and groups are local</quote>
 124                                 we are implying that they are stored only on the local system, in the
 125                                 <filename>/etc/passwd</filename> and <filename>/etc/group</filename> respectively.
 126                                 </para>
 127
 128                                 <para>
 129                                 For example, if an incoming SessionSetupAndX request is owned by the user
 130                                 <constant>BERYLIUM\WambatW</constant>, a system call will be made to look up
 131                                 the user <constant>WambatW</constant> in the <filename>/etc/passwd</filename>
 132                                 file.
 133                                 </para>
 134
 135                                 <para>
 136                                 This configuration may be used with stand-alone Samba servers, Domain Member
 137                                 servers (NT4 or ADS), and may be used for a PDC that uses either an smbpasswd
 138                                 or a tdbsam based Samba passdb backend.
 139                                 </para>
 140                         </listitem>
 141                 </varlistentry>
 142
 143                 <varlistentry><term>Winbind is not used, users and groups resolved via NSS: &smbmdash; </term>
 144                         <listitem>
 145                                 <para>
 146                                 In this situation user and group accounts are treated as if they are local
 147                                 accounts, the only way in which this differs from having local accounts is
 148                                 that the accounts are stored in a repository that can be shared. In practice
 149                                 this means that they will reside in either a NIS type database or else in LDAP.
 150                                 </para>
 151
 152                                 <para>
 153                                 This configuration may be used with stand-alone Samba servers, Domain Member
 154                                 servers (NT4 or ADS), and may be used for a PDC that uses either an smbpasswd
 155                                 or a tdbsam based Samba passdb backend.
 156                                 </para>
 157                         </listitem>
 158                 </varlistentry>
 159
 160                 <varlistentry><term>Winbind/NSS with the default local IDMAP table: &smbmdash; </term>
 161                         <listitem>
 162                                 <para>
 163                                 There are many sites that require only a simple Samba server, or a single Samba
 164                                 server that is a member of a Windows NT4 Domain or an ADS Domain. A typical example
 165                                 is an appliance like file server on which no local accounts are configured and
 166                                 winbind is used to obtain account credentials from the domain controllers for the
 167                                 domain. The domain control can be provided by Samba-3, MS Windows NT4 or MS Windows
 168                                 Active Directory.
 169                                 </para>
 170
 171                                 <para>
 172                                 Winbind is a great convenience in this situation. All that is needed is a range of
 173                                 UID numbers and GID numbers that can be defined in the &smb.conf; file, the
 174                                 <filename>/etc/nsswitch.conf</filename> file is configured to use <command>winbind</command>
 175                                 which does all the difficult work of mapping incoming SIDs to appropriate UIDs and GIDs.
 176                                 The SIDs are allocated a UID/GID in the order in which winbind receives them.
 177                                 </para>
 178
 179                                 <para>
 180                                 This configuration is not convenient or practical in sites that have more than one
 181                                 Samba server and that require the same UID or GID for the same user or group across
 182                                 all servers. One of the hazards of this method is that in the event that the winbind
 183                                 IDMAP file may become corrupted or lost, the repaired or rebuilt IDMAP file may allocate
 184                                 UIDs and GIDs to differing users and groups from what was there previously with the
 185                                 result that MS Windows files that are stored on the Samba server may now not belong to
 186                                 to rightful owner.
 187                                 </para>
 188                         </listitem>
 189                 </varlistentry>
 190
 191                 <varlistentry><term>Winbind/NSS uses RID based IDMAP: &smbmdash; </term>
 192                         <listitem>
 193                                 <para>
 194                                 <indexterm><primary>RID</primary></indexterm>
 195                                 <indexterm><primary>idmap_rid</primary></indexterm>
 196                                 <indexterm><primary>ADS</primary></indexterm>
 197                                 <indexterm><primary>LDAP</primary></indexterm>
 198                                 The IDMAP_RID facility is new to Samba version 3.0.8. It was added to make life easier
 199                                 for a number of sites that are committed to use of MS ADS, who do not want to apply
 200                                 an ADS schema extension, and who do not wish to install an LDAP directory server just for
 201                                 the purpose of maintaining an IDMAP table. If you have a single ADS domain (not a forest of
 202                                 domains, and not multiple domain trees) and you want a simple cookie-cutter solution to the
 203                                 IDMAP table problem, then IDMAP_RID is an obvious choice.
 204                                 </para>
 205
 206                                 <para>
 207                                 <indexterm><primary>idmap_rid</primary></indexterm>
 208                                 <indexterm><primary>idmap uid</primary></indexterm>
 209                                 <indexterm><primary>idmap gid</primary></indexterm>
 210                                 <indexterm><primary>RID</primary></indexterm>
 211                                 <indexterm><primary>SID</primary></indexterm>
 212                                 <indexterm><primary>UID</primary></indexterm>
 213                                 <indexterm><primary>idmap backend</primary></indexterm>
 214                                 This facility requires the allocation of the <parameter>idmap uid</parameter> and the
 215                                 <parameter>idmap gid</parameter> ranges, and within the <parameter>idmap uid</parameter>
 216                                 it is possible to allocate a sub-set of this range for automatic mapping of the relative
 217                                 identifier (RID) portion of the SID directly to the base of the UID plus the RID value.
 218                                 For example, if the <parameter>idmap uid</parameter> range is <constant>1000-100000000</constant>
 219                                 and the <parameter>idmap backend = idmap_rid:DOMAIN_NAME=1000-50000000</parameter>, and
 220                                 a SID is encountered that has the value <constant>S-1-5-21-34567898-12529001-32973135-1234</constant>,
 221                                 the resulting UID will be <constant>1000 + 1234 = 2234</constant>.
 222                                 </para>
 223                         </listitem>
 224                 </varlistentry>
 225
 226                 <varlistentry><term>Winbind with an NSS/LDAP backend based IDMAP facility: &smbmdash; </term>
 227                         <listitem>
 228                                 <para>
 229                                 <indexterm><primary>Domain Member</primary></indexterm>
 230                                 In this configuration <command>winbind</command> resolved SIDs to UIDs and GIDs from
 231                                 the <parameter>idmap uid</parameter> and <parameter>idmap gid</parameter> ranges specified
 232                                 in the &smb.conf; file, but instead of using a local winbind IDMAP table it is stored
 233                                 in an LDAP directory so that all Domain Member machines (clients and servers) can share
 234                                 a common IDMAP table.
 235                                 </para>
 236
 237                                 <para>
 238                                 <indexterm><primary>idmap backend</primary></indexterm>
 239                                 It is important that all LDAP IDMAP clients use only the master LDAP server as the
 240                                 <parameter>idmap backend</parameter> facility in the &smb.conf; file does not correctly
 241                                 handle LDAP redirects.
 242                                 </para>
 243                         </listitem>
 244                 </varlistentry>
 245
 246                 <varlistentry><term>Winbind with NSS to resolve UNIX/Linux user and group IDs: &smbmdash; </term>
 247                         <listitem>
 248                                 <para>
 249                                 The use of LDAP as the passdb backend is a smart solution for PDC, BDC as well as for
 250                                 Domain Member servers. It is a neat method for assuring that UIDs, GIDs and the matching
 251                                 SIDs will be consistent across all servers.
 252                                 </para>
 253
 254                                 <para>
 255                                 <indexterm><primary>LDAP</primary></indexterm>
 256                                 <indexterm><primary>PADL</primary></indexterm>
 257                                 The use of the LDAP based passdb backend requires use of the PADL nss_ldap utility, or
 258                                 an equivalent. In this situation winbind is used to handle foreign SIDs; ie: SIDs from
 259                                 stand-alone Windows clients (i.e.: not a member of our domain) as well as SIDs from
 260                                 another domain. The foreign UID/GID is mapped from allocated ranges (idmap uid and idmap gid)
 261                                 in precisely the same manner as when using winbind with a local IDMAP table.
 262                                 </para>
 263
 264                                 <para>
 265                                 <indexterm><primary>nss_ldap</primary></indexterm>
 266                                 <indexterm><primary>AD4UNIX</primary></indexterm>
 267                                 <indexterm><primary>MMC</primary></indexterm>
 268                                 The nss_ldap tool set can be used to access UIDs and GIDs via LDAP as well as via Active
 269                                 Directory. In order to use Active Directory it is necessary to modify the ADS schema by
 270                                 installing either the AD4UNIX schema extension or else use the Microsoft Services for UNIX
 271                                 version 3.5 of later to extend the ADS schema so it maintains UNIX account credentials.
 272                                 Where the ADS schema is extended a Microsoft Management Console (MMC) snap-in in also
 273                                 installed to permit the UNIX credentials to be set and managed from the ADS User and Computer
 274                                 management tool. Each account must be separately UNIX enabled before the UID and GID data can
 275                                 be used by Samba.
 276                                 </para>
 277                         </listitem>
 278                 </varlistentry>
 279
 280         </variablelist>
 281
 282         </sect2>
 283
 284         <sect2>
 285         <title>Primary Domain Controller</title>
 286
 287         <para>
 288         <indexterm><primary>domain security</primary></indexterm>
 289         <indexterm><primary>SID</primary></indexterm>
 290         <indexterm><primary>RID</primary></indexterm>
 291         <indexterm><primary>algorithmic mapping</primary></indexterm>
 292         Microsoft Windows domain security systems generate the user and group security identifier (SID) as part
 293         of the process of creation of an account. Windows does not have a concept of the UNIX UID or a GID, rather
 294         it has its own type of security descriptor. When Samba is used as a Domain Controller, it provides a method
 295         of producing a unique SID for each user and group. Samba generates a machine and a domain SID to which it
 296         adds a relative identifier (RID) that is calculated algorithmically from a base value that can be specified
 297         in the &smb.conf; file, plus twice (2X) the UID or GID. This method is called <quote>algorithmic mapping</quote>.
 298         </para>
 299
 300         <para>
 301         <indexterm><primary>RID base</primary></indexterm>
 302         For example, a user has a UID of 4321, and the algorithmic RID base has a value of 1000, the RID will
 303         be <constant>1000 + (2 x 4321) = 9642</constant>. Thus, if the domain SID is
 304         <constant>S-1-5-21-89238497-92787123-12341112</constant>, the resulting SID is
 305         <constant>S-1-5-21-89238497-92787123-12341112-9642</constant>.
 306         </para>
 307
 308         <para>
 309         <indexterm><primary>on-the-fly</primary></indexterm>
 310         The foregoing type SID is produced by Samba as an automatic function and is either produced on-the-fly
 311         (as in the case when using a <parameter>passdb backend = [tdbsam | smbpasswd]</parameter>, or may be stored
 312         as a permanent part of an account in an LDAP based ldapsam.
 313         </para>
 314
 315         <para>
 316         <indexterm><primary>SFU 3.5</primary></indexterm>
 317         MS Active Directory Server (ADS) uses a directory schema that can be extended to accommodate additional
 318         account attributes such as UIDs and GIDs. The installation of Microsoft Service for UNIX 3.5 will expand
 319         the normal ADS schema to include UNIX account attributes. These must of course be managed separately
 320         through a snap-in module to the normal ADS account management MMC interface.
 321         </para>
 322
 323         <para>
 324         <indexterm><primary>PDC</primary></indexterm>
 325         Security identifiers used within a domain must be managed to avoid conflict and to preserve itegrity.
 326         In an NT4 domain context that PDC manages the distribution of all security credentials to the backup
 327         domain controllers. At this time the only passdb backend for a Samba domain controller that is suitable
 328         for such information is an LDAP backend.
 329         </para>
 330
 331         </sect2>
 332
 333         <sect2>
 334         <title>Backup Domain Controller</title>
 335
 336         <para>
 337         <indexterm><primary>BDC</primary></indexterm>
 338         Backup Domain Controllers (BDCs) have read-only access to security credentials that are stored in LDAP.
 339         Changes in user or group account information are passed by the BDC to the PDC. Only the PDC can write
 340         changes to the directory.
 341         </para>
 342
 343         <para>
 344         IDMAP information can however be written directly to the LDAP server so long as all domain controllers
 345         have access to the master (writable) LDAP server. Samba-3 at this time does not handle LDAP redirects
 346         in the IDMAP backend. This means that it is is unsafe to use a slave (replicate) LDAP server with
 347         the IDMAP facility.
 348         </para>
 349
 350         </sect2>
 351
 352 </sect1>
 353
 354 <sect1>
 355 <title>Examples of IDMAP Backend Usage</title>
 356
 357 <para>
 358 <indexterm><primary>Domain Member Server</primary><see>DMS</see></indexterm>
 359 <indexterm><primary>Domain Member Client</primary><see>DMC</see></indexterm>
 360 <indexterm><primary>DMS</primary></indexterm>
 361 <indexterm><primary>DMC</primary></indexterm>
 362 Anyone who wishes to use <command>winbind</command> will find the following example configurations helpful.
 363 Remember that in the majority of cases <command>winbind</command> is of primary interest for use with
 364 Domain Member Servers (DMSs) and Domain Member Clients (DMCs).
 365 </para>
 366
 367         <sect2>
 368         <title>Default Winbind TDB</title>
 369
 370         <para>
 371         Two common configurations are used:
 372         </para>
 373
 374         <itemizedlist>
 375                 <listitem><para>
 376                 Networks that have an NT4 PDC (with or without BDCs) or a Samba PDC (with or without BDCs).
 377                 </para></listitem>
 378
 379                 <listitem><para>
 380                 Networks that use MS Windows 200X ADS.
 381                 </para></listitem>
 382         </itemizedlist>
 383
 384         <sect3>
 385         <title>NT4 Style Domains (includes Samba Domains)</title>
 386
 387         <para>
 388         The following is a simple example of an NT4 DMS &smb.conf; file that shows only the global section.
 389 <screen>
 390 #Global parameters
 391 [global]
 392         workgroup = MEGANET2
 393         security = DOMAIN
 394         idmap uid = 10000-20000
 395         idmap gid = 10000-20000
 396         template primary group = "Domain Users"
 397         template shell = /bin/bash
 398 </screen>
 399         </para>
 400
 401         <para>
 402         <indexterm><primary>winbind</primary></indexterm>
 403         <indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
 404         The use of <command>winbind</command> requires configuration of NSS. Edit the <filename>/etc/nsswitch.conf</filename>
 405         so it includes the following entries:
 406 <screen>
 407 ...
 408 passwd: files winbind
 409 shadow: files winbind
 410 group:  files winbind
 411 ...
 412 hosts:  files wins
 413 ...
 414 </screen>
 415         </para>
 416
 417         <para>
 418         The creation of the DMS requires the following steps:
 419         </para>
 420
 421         <procedure>
 422                 <step><para>
 423                 Create or install and &smb.conf; file with the above configuration.
 424                 </para></step>
 425
 426                 <step><para>
 427                 Execute:
 428 <screen>
 429 &rootprompt; net rpc join -UAdministrator%password
 430 Joined domain MEGANET2.
 431 </screen>
 432         <indexterm><primary>join</primary></indexterm>
 433         The success or failure of the join can be confirmed with the following command:
 434 <screen>
 435 &rootprompt; net rpc testjoin
 436 Join to 'MIDEARTH' is OK
 437 </screen>
 438                 A failed join would report an error message like the following:
 439                 <indexterm><primary>failed join</primary></indexterm>
 440 <screen>
 441 &rootprompt; net rpc testjoin
 442 [2004/11/05 16:34:12, 0] utils/net_rpc_join.c:net_rpc_join_ok(66)
 443 Join to domain 'MEGANET2' is not valid
 444 </screen>
 445                 </para></step>
 446
 447                 <step><para>
 448                 Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown.
 449                 </para></step>
 450         </procedure>
 451
 452         </sect3>
 453
 454         <sect3>
 455         <title>ADS Domains</title>
 456
 457         <para>
 458         <indexterm><primary>domain join</primary></indexterm>
 459         The procedure for joining and ADS domain is similar to the NT4 domain join, except the &smb.conf; file
 460         will have the following contents:
 461 <screen>
 462 # Global parameters
 463 [global]
 464         workgroup = BUTTERNET
 465         netbios name = GARGOYLE
 466         realm = BUTTERNET.BIZ
 467         security = ADS
 468         template shell = /bin/bash
 469         idmap uid = 500-10000000
 470         idmap gid = 500-10000000
 471         winbind use default domain = Yes
 472         winbind nested groups = Yes
 473         printer admin = "BUTTERNET\Domain Admins"
 474 </screen>
 475         </para>
 476
 477         <para>
 478         <indexterm><primary>KRB</primary></indexterm>
 479         <indexterm><primary>kerberos</primary></indexterm>
 480         <indexterm><primary>/etc/krb5.conf</primary></indexterm>
 481         <indexterm><primary>MIT</primary></indexterm>
 482         <indexterm><primary>MIT kerberos</primary></indexterm>
 483         <indexterm><primary>Heimdal</primary></indexterm>
 484         <indexterm><primary>Heimdal kerberos</primary></indexterm>
 485         ADS DMS operation requires use of kerberos (KRB). For this to work the <filename>krb5.conf</filename>
 486         must be configured. The exact requirements depends on which version of MIT or Heimdal kerberos is being
 487         used. It is sound advice to use only the latest version, which at this time are MIT kerberos version
 488         1.3.5 and Heimdal 0.61.
 489         </para>
 490
 491         <para>
 492         The creation of the DMS requires the following steps:
 493         </para>
 494
 495         <procedure>
 496                 <step><para>
 497                 Create or install and &smb.conf; file with the above configuration.
 498                 </para></step>
 499
 500                 <step><para>
 501                 Edit the <filename>/etc/nsswitch.conf</filename> file as shown above.
 502                 </para></step>
 503
 504                 <step><para>
 505                 Execute:
 506                 <indexterm><primary>net ads join</primary></indexterm>
 507 <screen>
 508 &rootprompt; net ads join -UAdministrator%password
 509 Joined domain BUTTERNET.
 510 </screen>
 511         The success or failure of the join can be confirmed with the following command:
 512 <screen>
 513 &rootprompt; net ads testjoin
 514 Using short domain name -- BUTTERNET
 515 Joined 'GARGOYLE' to realm 'BUTTERNET.BIZ'
 516 </screen>
 517         </para>
 518
 519         <para>
 520         An invalid or failed join can be detected by executing:
 521 <screen>
 522 &rootprompt; net ads testjoin
 523 GARGOYLE$@'s password:
 524 [2004/11/05 16:53:03, 0] utils/net_ads.c:ads_startup(186)
 525   ads_connect: No results returned
 526 Join to domain is not valid
 527 </screen>
 528                 <indexterm><primary>error message</primary></indexterm>
 529                 The specific error message may differ from the above as it depends on the type of failure that
 530                 may have occured. Increase the <parameter>log level</parameter> to 10, repeat the above test
 531                 and then examine the log files produced to identify the nature of the failure.
 532                 </para></step>
 533
 534                 <step><para>
 535                 Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown.
 536                 </para></step>
 537
 538         </procedure>
 539
 540         </sect3>
 541         </sect2>
 542
 543         <sect2>
 544         <title>IDMAP_RID with Winbind</title>
 545
 546         <para>
 547         <indexterm><primary>idmap_rid</primary></indexterm>
 548         <indexterm><primary>SID</primary></indexterm>
 549         <indexterm><primary>RID</primary></indexterm>
 550         <indexterm><primary>IDMAP</primary></indexterm>
 551         The <command>idmap_rid</command> facility is a new tool that, unlike native winbind, creates a
 552         predictable mapping of MS Windows SIDs to UNIX UIDs and GIDs. The key benefit of this method
 553         of implementing the Samba IDMAP facility is that it eliminates the need to store the IDMAP data
 554         in a central place. The down-side is that it can be used only within a single ADS Domain and
 555         is not compatible with trusted domain implementations.
 556         </para>
 557
 558         <para>
 559         <indexterm><primary>SID</primary></indexterm>
 560         <indexterm><primary>allow trusted domains</primary></indexterm>
 561         <indexterm><primary>idmap uid</primary></indexterm>
 562         <indexterm><primary>idmap gid</primary></indexterm>
 563         This alternate method of SID to UID/GID  mapping can be achieved uses the idmap_rid
 564         plug-in. This plug-in uses the RID of the user SID to derive the UID and GID by adding the
 565         RID to a base value specified. This utility requires that the parameter
 566         <quote>allow trusted domains = No</quote> must be specified, as it is not compatible
 567         with multiple domain environments. The <parameter>idmap uid</parameter> and
 568         <parameter>idmap gid</parameter> ranges must be specified.
 569         </para>
 570
 571         <para>
 572         <indexterm><primary>idmap_rid</primary></indexterm>
 573         <indexterm><primary>realm</primary></indexterm>
 574         The idmap_rid facility can be used both for NT4/Samba style domains as well as with Active Directory.
 575         To use this with an NT4 Domain the <parameter>realm</parameter> is not used, additionally the
 576         method used to join the domain uses the <constant>net rpc join</constant> process.
 577         </para>
 578
 579         <para>
 580         An example &smb.conf; file for and ADS domain environment is shown here:
 581 <screen>
 582 # Global parameters
 583 [global]
 584         workgroup = KPAK
 585         netbios name = BIGJOE
 586         realm = CORP.KPAK.COM
 587         server string = Office Server
 588         security = ADS
 589         allow trusted domains = No
 590         idmap backend = idmap_rid:KPAK=500-100000000
 591         idmap uid = 500-100000000
 592         idmap gid = 500-100000000
 593         template shell = /bin/bash
 594         winbind use default domain = Yes
 595         winbind enum users = No
 596         winbind enum groups = No
 597         winbind nested groups = Yes
 598         printer admin = "Domain Admins"
 599 </screen>
 600         </para>
 601
 602         <para>
 603         <indexterm><primary>large domain</primary></indexterm>
 604         <indexterm><primary>Active Directory</primary></indexterm>
 605         <indexterm><primary>response</primary></indexterm>
 606         <indexterm><primary>getent</primary></indexterm>
 607         In a large domain with many users it is imperative to disable enumeration of users and groups.
 608         For examplem, at a site that has 22,000 users in Active Directory the winbind based user and
 609         group resolution is unavailable for nearly 12 minutes following first start-up of
 610         <command>winbind</command>. Disabling of such enumeration resulted in instantaneous response.
 611         The disabling of user and group enumeration means that it will not be possible to list users
 612         or groups using the <command>getent passwd</command> and <command>getent group</command>
 613         commands. It will be possible to perform the lookup for individual users, as shown in the procedure
 614         below.
 615         </para>
 616
 617         <para>
 618         <indexterm><primary>NSS</primary></indexterm>
 619         <indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
 620         The use of this tool requires configuration of NSS as per the native use of winbind. Edit the
 621         <filename>/etc/nsswitch.conf</filename> so it has the following parameters:
 622 <screen>
 623 ...
 624 passwd: files winbind
 625 shadow: files winbind
 626 group:  files winbind
 627 ...
 628 hosts:  files wins
 629 ...
 630 </screen>
 631         </para>
 632
 633         <para>
 634         The following procedure can be used to utilize the idmap_rid facility:
 635         </para>
 636
 637         <procedure>
 638                 <step><para>
 639                 Create or install and &smb.conf; file with the above configuration.
 640                 </para></step>
 641
 642                 <step><para>
 643                 Edit the <filename>/etc/nsswitch.conf</filename> file as shown above.
 644                 </para></step>
 645
 646                 <step><para>
 647                 Execute:
 648 <screen>
 649 &rootprompt; net ads join -UAdministrator%password
 650 Using short domain name -- KPAK
 651 Joined 'BIGJOE' to realm 'CORP.KPAK.COM'
 652 </screen>
 653                 </para>
 654
 655                 <para>
 656                 <indexterm><primary>failed join</primary></indexterm>
 657                 An invalid or failed join can be detected by executing:
 658 <screen>
 659 &rootprompt; net ads testjoin
 660 BIGJOE$@'s password:
 661 [2004/11/05 16:53:03, 0] utils/net_ads.c:ads_startup(186)
 662   ads_connect: No results returned
 663 Join to domain is not valid
 664 </screen>
 665                 The specific error message may differ from the above as it depends on the type of failure that
 666                 may have occured. Increase the <parameter>log level</parameter> to 10, repeat the above test
 667                 and then examine the log files produced to identify the nature of the failure.
 668                 </para></step>
 669
 670                 <step><para>
 671                 Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown.
 672                 </para></step>
 673
 674                 <step><para>
 675                 Validate the operation of this configuration by executing:
 676                 <indexterm><primary></primary></indexterm>
 677 <screen>
 678 &rootprompt; getent passwd administrator
 679 administrator:x:1000:1013:Administrator:/home/BE/administrator:/bin/bash
 680 </screen>
 681                 </para></step>
 682         </procedure>
 683
 684         </sect2>
 685
 686         <sect2>
 687         <title>IDMAP Storage in LDAP using Winbind</title>
 688
 689         <para>
 690         <indexterm><primary>ADAM</primary></indexterm>
 691         <indexterm><primary>ADS</primary></indexterm>
 692         The storage of IDMAP information in LDAP can be used with both NT4/Samba-3 style domains as well as
 693         with ADS domains. OpenLDAP is a commonly used LDAP server for this purpose, although any standards
 694         complying LDAP server can be used. It is therefore possible to deploy this IDMAP configuration using
 695         the Sun iPlanet LDAP server, Novell eDirectory, Microsoft ADS plus ADAM, and so on.
 696         </para>
 697
 698         <para>
 699         The following example is for an ADS style domain:
 700         </para>
 701
 702         <para>
 703 <screen>
 704 # Global parameters
 705 [global]
 706         workgroup = SNOWSHOW
 707         netbios name = GOODELF
 708         realm = SNOWSHOW.COM
 709         server string = Samba Server
 710         security = ADS
 711         log level = 1 ads:10 auth:10 sam:10 rpc:10
 712         ldap admin dn = cn=Manager,dc=SNOWSHOW,dc=COM
 713         ldap idmap suffix = ou=Idmap
 714         ldap suffix = dc=SNOWSHOW,dc=COM
 715         idmap backend = ldap:ldap://ldap.snowshow.com
 716         idmap uid = 150000-550000
 717         idmap gid = 150000-550000
 718         template shell = /bin/bash
 719         winbind use default domain = Yes
 720 </screen>
 721         </para>
 722
 723         <para>
 724         <indexterm><primary>realm</primary></indexterm>
 725         In the case of an NT4 or Samba-3 style Domain the <parameter>realm</parameter> is not used and the
 726         command used to join the domain is: <command>net rpc join</command>. The above example also demonstrates
 727         advanced error reporting techniques that are documented in <link linkend="dbglvl">the chapter called
 728         Reporting Bugs</link>.
 729         </para>
 730
 731         <para>
 732         <indexterm><primary>MIT kerberos</primary></indexterm>
 733         <indexterm><primary>Heimdal kerberos</primary></indexterm>
 734         <indexterm><primary>/etc/krb5.conf</primary></indexterm>
 735         Where MIT kerberos is installed (version 1.3.4 or later) edit the <filename>/etc/krb5.conf</filename>
 736         file so it has the following contents:
 737 <screen>
 738 [logging]
 739  default = FILE:/var/log/krb5libs.log
 740  kdc = FILE:/var/log/krb5kdc.log
 741  admin_server = FILE:/var/log/kadmind.log
 742
 743 [libdefaults]
 744  default_realm = SNOWSHOW.COM
 745  dns_lookup_realm = false
 746  dns_lookup_kdc = true
 747
 748 [appdefaults]
 749  pam = {
 750    debug = false
 751    ticket_lifetime = 36000
 752    renew_lifetime = 36000
 753    forwardable = true
 754    krb4_convert = false
 755  }
 756 </screen>
 757         </para>
 758
 759         <para>
 760         Where Heimdal kerberos is installed edit the <filename>/etc/krb5.conf</filename>
 761         file so it is either empty (i.e.: no contents) or it has the following contents:
 762 <screen>
 763 [libdefaults]
 764         default_realm = SNOWSHOW.COM
 765         clockskew = 300
 766
 767 [realms]
 768         SNOWSHOW.COM = {
 769                 kdc = ADSDC.SHOWSHOW.COM
 770         }
 771
 772 [domain_realm]
 773         .snowshow.com = SNOWSHOW.COM
 774 </screen>
 775         </para>
 776
 777         <note><para>
 778         Samba can not use the Heimdal libraries if there is no <filename>/etc/krb5.conf</filename> file.
 779         So long as there is an empty file the Heimdal kerberos libraries will be usable. There is no
 780         need to specify any settings as Samba using the Heimdal libraries can figure this out automatically.
 781         </para></note>
 782
 783         <para>
 784         Edit the NSS control file <filename>/etc/nsswitch.conf</filename> so it has the following entries:
 785 <screen>
 786 ...
 787 passwd: files ldap
 788 shadow: files ldap
 789 group:  files ldap
 790 ...
 791 hosts:  files wins
 792 ...
 793 </screen>
 794         </para>
 795
 796         <para>
 797         <indexterm><primary>PADL</primary></indexterm>
 798         <indexterm><primary>/etc/ldap.conf</primary></indexterm>
 799         You will need the <ulink url="http://www.padl.com">PADL</ulink> <command>nss_ldap</command>
 800         tool set for this solution. Configure the <filename>/etc/ldap.conf</filename> file so it has
 801         the information needed. The following is an example of a working file:
 802 <screen>
 803 host    192.168.2.1
 804 base    dc=snowshow,dc=com
 805 binddn  cn=Manager,dc=snowshow,dc=com
 806 bindpw  not24get
 807
 808 pam_password exop
 809
 810 nss_base_passwd ou=People,dc=snowshow,dc=com?one
 811 nss_base_shadow ou=People,dc=snowshow,dc=com?one
 812 nss_base_group  ou=Groups,dc=snowshow,dc=com?one
 813 ssl     no
 814 </screen>
 815         </para>
 816
 817         <para>
 818         The following procedure may be followed to affect a working configuration:
 819         </para>
 820
 821         <procedure>
 822                 <step><para>
 823                 Configure the &smb.conf; file as shown above.
 824                 </para></step>
 825
 826                 <step><para>
 827                 Create the <filename>/etc/krb5.conf</filename> file following the indications above.
 828                 </para></step>
 829
 830                 <step><para>
 831                 Configure the <filename>/etc/nsswitch.conf</filename> file as shown above.
 832                 </para></step>
 833
 834                 <step><para>
 835                 Download, build and install the PADL nss_ldap tool set. Configure the
 836                 <filename>/etc/ldap.conf</filename> file as shown above.
 837                 </para></step>
 838
 839                 <step><para>
 840                 Configure an LDAP server, initialize the directory with the top level entries needed by IDMAP
 841                 as shown in the following LDIF file:
 842 <screen>
 843 dn: dc=snowshow,dc=com
 844 objectClass: dcObject
 845 objectClass: organization
 846 dc: snowshow
 847 o: The Greatest Snow Show in Singapore.
 848 description: Posix and Samba LDAP Identity Database
 849
 850 dn: cn=Manager,dc=snowshow,dc=com
 851 objectClass: organizationalRole
 852 cn: Manager
 853 description: Directory Manager
 854
 855 dn: ou=Idmap,dc=snowshow,dc=com
 856 objectClass: organizationalUnit
 857 ou: idmap
 858 </screen>
 859                 </para></step>
 860
 861                 <step><para>
 862                 Execute the command to join the Samba Domain Member Server to the ADS domain as shown here:
 863 <screen>
 864 &rootprompt; net ads testjoin
 865 Using short domain name -- SNOWSHOW
 866 Joined 'GOODELF' to realm 'SNOWSHOW.COM'
 867 </screen>
 868                 </para></step>
 869
 870                 <step><para>
 871                 Store the LDAP server access password in the Samba <filename>secrets.tdb</filename> file as follows:
 872 <screen>
 873 &rootprompt; smbpasswd -w not24get
 874 </screen>
 875                 </para></step>
 876
 877                 <step><para>
 878                 Start the <command>nmbd, winbind,</command> and <command>smbd</command> daemons in the order shown.
 879                 </para></step>
 880         </procedure>
 881
 882         <para>
 883         <indexterm><primary>diagnostic</primary></indexterm>
 884         Follow the diagnositic procedures shown earlier in this chapter to identify success or failure of the join.
 885         In many cases a failure is indicated by a silent return to the command prompt with no indication of the
 886         reason for failure.
 887         </para>
 888
 889         </sect2>
 890
 891         <sect2>
 892         <title>IDMAP and NSS Using LDAP From ADS with RFC2307bis Schema Extension</title>
 893
 894         <para>
 895         <indexterm><primary>rfc2307bis</primary></indexterm>
 896         <indexterm><primary>schema</primary></indexterm>
 897         The use of this method is messy. The information provided in the following is for guidance only
 898         and is very definitely not complete. This method does work; it is used in a number of large sites
 899         and has an acceptable level of performance.
 900         </para>
 901
 902         <para>
 903         The following is an example &smb.conf; file:
 904 <screen>
 905 # Global parameters
 906 [global]
 907         workgroup = BOBBY
 908         realm = BOBBY.COM
 909         security = ADS
 910         idmap uid = 150000-550000
 911         idmap gid = 150000-550000
 912         template shell = /bin/bash
 913         winbind cache time = 5
 914         winbind use default domain = Yes
 915         winbind trusted domains only = Yes
 916         winbind nested groups = Yes
 917 </screen>
 918         </para>
 919
 920         <para>
 921         <indexterm><primary>nss_ldap</primary></indexterm>
 922         The DMS must be joined to the domain using the usual procedure. Additionally, it is necessary
 923         to build and install the PADL nss_ldap tool set. Be sure to build this tool set with the
 924         following:
 925 <screen>
 926 ./configure --enable-rfc2307bis --enable-schema-mapping
 927 make install
 928 </screen>
 929         </para>
 930
 931         <para>
 932         <indexterm><primary>/etc/nsswitch.conf</primary></indexterm>
 933         The following <filename>/etc/nsswitch.conf</filename> file contents are required:
 934 <screen>
 935 ...
 936 passwd: files ldap
 937 shadow: files ldap
 938 group:  files ldap
 939 ...
 940 hosts:  files wins
 941 ...
 942 </screen>
 943         </para>
 944
 945         <para>
 946         <indexterm><primary>/etc/ldap.conf</primary></indexterm>
 947         <indexterm><primary>nss_ldap</primary></indexterm>
 948         The <filename>/etc/ldap.conf</filename> file must be configured also. Refer to the PADL documentation
 949         and source code for nss_ldap to specific instructions.
 950         </para>
 951
 952         <para>
 953         The next step involves preparation on the ADS schema. This is briefly discussed in the remaining
 954         part of this chapter.
 955         </para>
 956
 957                 <sect3>
 958                 <title>IDMAP, Active Directory and MS Services for UNIX 3.5</title>
 959
 960                 <para>
 961                 <indexterm><primary>SFU</primary></indexterm>
 962                 The Microsoft Windows Service for UNIX (SFU) version 3.5 is available for free
 963                 <ulink url="http://www.microsoft.com/windows/sfu/">download</ulink>
 964                 from the Microsoft Web site. You will need to download this tool and install it following
 965                 Microsoft instructions.
 966                 </para>
 967
 968                 </sect3>
 969
 970                 <sect3>
 971                 <title>IDMAP, Active Directory and AD4UNIX</title>
 972
 973                 <para>
 974                 Instructions for obtaining and installing the AD4UNIX tool set can be found from the
 975                 <ulink url="http://www.geekcomix.com/cgi-bin/classnotes/wiki.pl?LDAP01/An_Alternative_Approach">
 976                 Geekcomix</ulink> web site.
 977                 </para>
 978
 979                 </sect3>
 980
 981         </sect2>
 982
 983 </sect1>
 984
 985 </chapter>