docs-xml/manpages/idmap_script.8.xml

   1 <?xml version="1.0" encoding="iso-8859-1"?>
   2 <!DOCTYPE refentry PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
   3 <refentry id="idmap_script.8">
   4
   5 <refmeta>
   6         <refentrytitle>idmap_script</refentrytitle>
   7         <manvolnum>8</manvolnum>
   8         <refmiscinfo class="source">Samba</refmiscinfo>
   9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
  10         <refmiscinfo class="version">&doc.version;</refmiscinfo>
  11 </refmeta>
  12
  13
  14 <refnamediv>
  15         <refname>idmap_script</refname>
  16         <refpurpose>Samba's idmap_script Backend for Winbind</refpurpose>
  17 </refnamediv>
  18
  19 <refsynopsisdiv>
  20         <title>DESCRIPTION</title>
  21
  22         <para>
  23         The idmap_script plugin is a substitute for the idmap_tdb2
  24         backend used by winbindd for storing SID/uid/gid mapping tables
  25         in clustered environments with Samba and CTDB. It is a read only
  26         backend that uses a script to perform mapping.
  27         </para>
  28
  29         <para>
  30         It was developed out of the idmap_tdb2 back end and does not store
  31         SID/uid/gid mappings in a TDB, since the winbind_cache tdb will
  32         store the mappings once they are provided.
  33         </para>
  34 </refsynopsisdiv>
  35
  36 <refsect1>
  37         <title>IDMAP OPTIONS</title>
  38
  39         <variablelist>
  40                 <varlistentry>
  41                 <term>range = low - high</term>
  42                 <listitem><para>
  43                         Defines the available matching uid and gid range for which the
  44                         backend is authoritative.
  45                 </para></listitem>
  46                 </varlistentry>
  47
  48                 <varlistentry>
  49                 <term>script</term>
  50                 <listitem><para>
  51                         This option can be used to configure an external program
  52                         for performing id mappings.
  53                 </para></listitem>
  54                 </varlistentry>
  55         </variablelist>
  56 </refsect1>
  57
  58 <refsect1>
  59         <title>IDMAP SCRIPT</title>
  60
  61         <para>
  62         The script idmap backend supports an external program for performing id mappings
  63         through the &smb.conf; option <parameter>idmap config * : script</parameter> or
  64         its deprecated legacy form <parameter>idmap : script</parameter>.
  65         </para>
  66
  67         <para>
  68         The script should accept the following command line options.
  69         </para>
  70
  71         <programlisting>
  72         SIDTOID S-1-xxxx
  73         IDTOSID UID xxxx
  74         IDTOSID GID xxxx
  75         IDTOSID XID xxxx
  76         </programlisting>
  77
  78         <para>
  79         And it should return one of the following responses as a single line of
  80         text.
  81         </para>
  82
  83         <programlisting>
  84         UID:yyyy
  85         GID:yyyy
  86         XID:yyyy
  87         SID:ssss
  88         ERR:yyyy
  89         </programlisting>
  90
  91         <para>
  92         XID indicates that the ID returned should be both a UID and a GID.
  93         That is, it requests an ID_TYPE_BOTH, but it is ultimately up to
  94         the script whether or not it can honor that request. It can choose
  95         to return a UID or a GID mapping only.
  96         </para>
  97 </refsect1>
  98
  99 <refsect1>
 100         <title>EXAMPLES</title>
 101
 102         <para>
 103         This example shows how script is used as the default idmap backend
 104         using an external program via the script parameter:
 105         </para>
 106
 107         <programlisting>
 108         [global]
 109         idmap config * : backend = script
 110         idmap config * : range = 1000000-2000000
 111         idmap config * : script = /usr/local/samba/bin/idmap_script.sh
 112         </programlisting>
 113
 114         <para>
 115         This shows a simple script to partially perform the task:
 116         </para>
 117
 118         <programlisting>
 119         #!/bin/sh
 120         #
 121         # Uncomment this if you want some logging
 122         #echo $@ >> /tmp/idmap.sh.log
 123         if [ "$1" == "SIDTOID" ]
 124         then
 125                 # Note. The number returned has to be within the range defined
 126                 #echo "Sending UID:1000005" >> /tmp/idmap.sh.log
 127                 echo "UID:1000005"
 128                 exit 0
 129         else
 130                 #echo "Sending ERR: No idea what to do" >> /tmp/idmap.sh.log
 131                 echo "ERR: No idea what to do"
 132                 exit 1
 133         fi
 134         </programlisting>
 135
 136         <para>
 137         Clearly, this script is not enough, as it should probably use wbinfo
 138         to determine if an incoming SID is a user or group SID and then
 139         look up the mapping in a table or use some other mechanism for
 140         mapping SIDs to UIDs and etc.
 141         </para>
 142
 143         <para>
 144           Please be aware that the script is called with the
 145           _NO_WINBINDD environment variable set to 1. This prevents
 146           recursive calls into winbind from the script both via
 147           explicit calls to wbinfo and via implicit calls via
 148           nss_winbind. For example a call to <command>ls -l</command>
 149           could trigger such an infinite recursion.
 150         </para>
 151
 152         <para>
 153           It is safe to call <command>wbinfo -n</command> and
 154           <command>wbinfo -s</command> from within an idmap script. To
 155           do so, the script must unset the _NO_WINBINDD environment
 156           variable right before the call to <command>wbinfo</command>
 157           and set it to 1 again right after <command>wbinfo</command>
 158           has returned to protect against the recursion.
 159         </para>
 160 </refsect1>
 161
 162 <refsect1>
 163         <title>AUTHOR</title>
 164
 165         <para>
 166         The original Samba software and related utilities
 167         were created by Andrew Tridgell. Samba is now developed
 168         by the Samba Team as an Open Source project similar
 169         to the way the Linux kernel is developed.
 170         </para>
 171 </refsect1>
 172
 173 </refentry>