source: vendor/3.5.0/examples/scripts/idmap/README

idmap script option for flexible UID/GID handling
-------------------------------------------------

If you are using "idmap backend = tdb2" with winbind in Samba3, then
you have the option of specifying an external script to perform
uid/gid allocation. This can be useful in situations where you are
using AD for authentication, but the AD server is not configured to
supply uid/gid mappings via the services for unix extensions and you
have a need to support a pre-existing system for uid/gid allocation.

One common situation where this arises is where you have a mixture of
NFS and CIFS clients, and the NFS clients are configured to use NIS
for their id mapping. It is quite common to have an administrative
mechanism in place to ensure that all of the NIS users have a
corresponding AD user account, but there may be no direct mechanism to
ensure that any unix uid/gid attributes in AD match those in NIS.

In this situation it would normally not be possible to share files
with correct ownership between the CIFS and NFS clients, as winbind
would normally allocate its own set of UIDs from a reserved pool, and
those uids won't match the existing ones in NIS.

The idmap script option
-----------------------

To resolve this problem the idmap tdb2 module has the ability to call
out to an external script whenever it meeds an unknown SID or UID/GID
for the first time. It is then the job of that script to provide a
mapping consistent with whatever external system is in place (such as
NIS), and return the mapped result to winbind.

Winbind will then persistently store the result of the mapping, so
that the script is not invoked more than once per user/group.

To setup the idmap script you need to set the following options:

  idmap backend = tdb2
  idmap script = /usr/local/bin/idmap.sh

where the location and name of the script is arbitrary. It just needs
to be executable by winbind. 

You then need to stop Samba, delete the key idmap cache files, and
restart Samba. The idmap files that need to be deleted are:

 - gencache.tdb
 - winbindd_cache.tdb
 - idmap2.tdb


Script operation
----------------

The script will be called by winbind in one of three ways. 

 1) idmap.sh SIDTOID <SID>
 2) idmap.sh IDTOSID UID <UID>
 2) idmap.sh IDTOSID GID <GID>

In the first form the script is being asked to map a windows SID (in
the string form "S-*") to a UID or GID. In the second form the script
is being asked to map a UID to a SID, and in the third form it is
being asked to map a GID to a SID.

SIDTOID
-------

In the first form the script is expected to output a UID or GID given
a SID. The output format is expected to be like this:

 UID:1234
or
 GID:1122

If the SID cannot be found, then the script should output an error
like this:

 ERR:Some error message

Note that it is common for the external mechanism to not know about
windows SIDs, in which case the script may use the wbinfo command to
ask winbind to change the SID into a username or group name. The
"wbinfo -s" option is the one to use.


IDTOSID UID
-----------

In this form the script is expected to turn a UID into a SID,
returning a result like this:

 SID:S-1-5-21-1110277820-2343689819-414998773-1124

or an error like this:

 ERR:Some error message

If the external mechanism that the script wants to use cannot produce
a SID, but can produce a username, then the script can convert the
username to a SID using the "wbinfo -n" option.

IDTOSID GID
-----------

In this form the script is expected to turn a GID into a SID,
returning a result like this:

 SID:S-1-5-21-1110277820-2343689819-414998773-1120

or an error like this:

 ERR:Some error message

If the external mechanism that the script wants to use cannot produce
a SID, but can produce a group name, then the script can convert the
groupname to a SID using the "wbinfo -n" option.


Testing the script
------------------

It is suggested that you test the script on the command line first,
before using it in winbind. To do that first get a list of users you
would like to test using the command "wbinfo -u". Let's assume one of
those users is "DC01\tridge". You would then test the script as
follows:

  [root ~]# wbinfo -n 'DC01\tridge'
  S-1-5-21-1110277820-2343689819-414998773-1124 User (1)

  [root ~]# /usr/local/bin/idmap.sh SIDTOID S-1-5-21-1110277820-2343689819-414998773-1124
  UID:1003

  [root ~]# /usr/local/bin/idmap.sh IDTOSID UID 1003
  SID:S-1-5-21-1110277820-2343689819-414998773-1124

Once those steps pass, you can enable the script in winbind
(remembering to clear the cache tdbs), and test using the id command:

  [root ~]# id 'DC01\tridge'
  uid=1003(DC01\tridge) gid=10000009(DC01\domain users)


nsswitch.conf
-------------

When using the idmap script option you setup nsswitch.conf as usual
for winbind, with one addition. If your external idmap mechanism
support nsswitch then you may optionally choose to add it to
nsswitch.conf, but you must add it after the winbind entry. So for
example, if using NIS, you could have a nsswitch.conf entry like this:

  passwd:     files winbind nis
  group:      files winbind nis

Adding this to nsswitch.conf is not essential, but may be useful for
some local administration tools.

Sample script
-------------

This directory contains a simple example script 'idmap_nis.sh' that
provides idmap script support for NIS. To use it you first need to
enable the NIS client on your Samba server, usually by configuring
/etc/yp.conf. See the manual page for yp.conf for details. 

You should test the ypcat and ypmatch commands and make sure they work
before enabling the idmap_nis.sh script.