1faf59085f156979fec20c1188d6943bdae95995
[kai/samba.git] / docs-xml / manpages / idmap_tdb2.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_tdb2.8">
4
5 <refmeta>
6         <refentrytitle>idmap_tdb2</refentrytitle>
7         <manvolnum>8</manvolnum>
8         <refmiscinfo class="source">Samba</refmiscinfo>
9         <refmiscinfo class="manual">System Administration tools</refmiscinfo>
10         <refmiscinfo class="version">3.6</refmiscinfo>
11 </refmeta>
12
13
14 <refnamediv>
15         <refname>idmap_tdb2</refname>
16         <refpurpose>Samba's idmap_tdb2 Backend for Winbind</refpurpose>
17 </refnamediv>
18
19 <refsynopsisdiv>
20         <title>DESCRIPTION</title>
21
22         <para>
23         The idmap_tdb2 plugin is a substitute for the default idmap_tdb
24         backend used by winbindd for storing SID/uid/gid mapping tables
25         in clustered environments with Samba and CTDB.
26         </para>
27
28         <para>
29         In contrast to read only backends like idmap_rid, it is an allocating
30         backend: This means that it needs to allocate new user and group IDs in
31         order to create new mappings.
32         </para>
33 </refsynopsisdiv>
34
35 <refsect1>
36         <title>IDMAP OPTIONS</title>
37
38         <variablelist>
39                 <varlistentry>
40                 <term>range = low - high</term>
41                 <listitem><para>
42                         Defines the available matching uid and gid range for which the
43                         backend is authoritative.
44                 </para></listitem>
45                 </varlistentry>
46
47                 <varlistentry>
48                 <term>script</term>
49                 <listitem><para>
50                         This option can be used to configure an external program
51                         for performing id mappings instead of using the tdb
52                         counter. The mappings are then stored int tdb2 idmap
53                         database. For details see the section on IDMAP SCRIPT below.
54                 </para></listitem>
55                 </varlistentry>
56         </variablelist>
57 </refsect1>
58
59 <refsect1>
60         <title>IDMAP SCRIPT</title>
61
62         <para>
63         The tdb2 idmap backend supports an external program for performing id mappings
64         through the smb.conf option <parameter>idmap config * : script</parameter> or
65         its deprecated legacy form <parameter>idmap : script</parameter>.
66         </para>
67
68         <para>
69         The mappings obtained by the script are then stored in the idmap tdb2
70         database instead of mappings created by the incrementing id counters.
71         It is therefore important that the script covers the complete range of
72         SIDs that can be passed in for SID to Unix ID mapping, since otherwise
73         SIDs unmapped by the script might get mapped to IDs that had
74         previously been mapped by the script.
75         </para>
76
77         <para>
78         The script should accept the following command line options.
79         </para>
80
81         <programlisting>
82         SIDTOID S-1-xxxx
83         IDTOSID UID xxxx
84         IDTOSID GID xxxx
85         </programlisting>
86
87         <para>
88         And it should return one of the following responses as a single line of
89         text.
90         </para>
91
92         <programlisting>
93         UID:yyyy
94         GID:yyyy
95         SID:yyyy
96         ERR:yyyy
97         </programlisting>
98 </refsect1>
99
100 <refsect1>
101         <title>EXAMPLES</title>
102
103         <para>
104         This example shows how tdb2 is used as a the default idmap backend.
105         </para>
106
107         <programlisting>
108         [global]
109         idmap config * : backend = tdb2
110         idmap config * : range = 1000000-2000000
111         </programlisting>
112
113         <para>
114         This example shows how tdb2 is used as a the default idmap backend
115         using an external program via the script parameter:
116         </para>
117
118         <programlisting>
119         [global]
120         idmap config * : backend = tdb2
121         idmap config * : range = 1000000-2000000
122         idmap config * : script = /usr/local/samba/bin/idmap_script.sh
123         </programlisting>
124 </refsect1>
125
126 <refsect1>
127         <title>AUTHOR</title>
128
129         <para>
130         The original Samba software and related utilities
131         were created by Andrew Tridgell. Samba is now developed
132         by the Samba Team as an Open Source project similar
133         to the way the Linux kernel is developed.
134         </para>
135 </refsect1>
136
137 </refentry>