1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % global_entities SYSTEM '../entities/global.entities'>
7 <chapter id="upgrading-to-3.0">
12 <pubdate>June 30, 2003</pubdate>
15 <title>Upgrading from Samba-2.x to Samba-3.0.0</title>
18 This chapter deals exclusively with the differences between Samba-3.0.0 and Samba-2.2.8a.
19 It points out where configuration parameters have changed, and provides a simple guide for
20 the move from 2.2.x to 3.0.0.
24 <title>Quick Migration Guide</title>
27 Samba-3.0.0 default behavior should be approximately the same as Samba-2.2.x.
28 The default behavior when the new parameter <smbconfoption><name>passdb backend</name></smbconfoption>
29 is not defined in the &smb.conf; file provides the same default behavior as Samba-2.2.x
30 with <smbconfoption><name>encrypt passwords</name><value>Yes</value></smbconfoption>, and
31 will use the <filename>smbpasswd</filename> database.
35 So why say that <emphasis>behavior should be approximately the same as Samba-2.2.x?</emphasis> Because
36 Samba-3.0.0 can negotiate new protocols, such as support for native Unicode, that may result in
37 differing protocol code paths being taken. The new behavior under such circumstances is not
38 exactly the same as the old one. The good news is that the domain and machine SIDs will be
39 preserved across the upgrade.
43 If the Samba-2.2.x system was using an LDAP backend, and there is no time to update the LDAP
44 database, then make sure that <smbconfoption><name>passdb backend</name><value>ldapsam_compat</value></smbconfoption>
45 is specified in the &smb.conf; file. For the rest, behavior should remain more or less the same.
46 At a later date, when there is time to implement a new Samba-3 compatible LDAP backend, it is possible
47 to migrate the old LDAP database to the new one through use of the <command>pdbedit</command>.
48 See <link linkend="pdbeditthing">The <emphasis>pdbedit</emphasis> Command</link>.
54 <title>New Features in Samba-3</title>
57 The major new features are:
60 <orderedlist numeration="arabic">
62 Active Directory support. This release is able to join an ADS realm
63 as a member server and authenticate users using LDAP/Kerberos.
67 Unicode support. Samba will now negotiate Unicode on the wire and
68 internally there is a much better infrastructure for multi-byte
69 and Unicode character sets.
73 New authentication system. The internal authentication system has
74 been almost completely rewritten. Most of the changes are internal,
75 but the new authoring system is also very configurable.
79 New filename mangling system. The filename mangling system has been
80 completely rewritten. An internal database now stores mangling maps
85 New <quote>net</quote> command. A new <quote>net</quote> command has been added. It is
86 somewhat similar to the <quote>net</quote> command in Windows. Eventually, we
87 plan to replace a bunch of other utilities (such as smbpasswd)
88 with subcommands in <quote>net</quote>.
92 Samba now negotiates NT-style status32 codes on the wire. This
93 considerably improves error handling.
97 Better Windows 200x/XP printing support including publishing
98 printer attributes in Active Directory.
102 New loadable RPC modules for passdb backends and character sets.
106 New default dual-daemon winbindd support for better performance.
110 Support for migrating from a Windows NT 4.0 domain to a Samba
111 domain and maintaining user, group and domain SIDs.
115 Support for establishing trust relationships with Windows NT 4.0
120 Initial support for a distributed Winbind architecture using
121 an LDAP directory for storing SID to UID/GID mappings.
125 Major updates to the Samba documentation tree.
129 Full support for client and server SMB signing to ensure
130 compatibility with default Windows 2003 security settings.
135 Plus lots of other improvements!
141 <title>Configuration Parameter Changes</title>
144 This section contains a brief listing of changes to &smb.conf; options
145 in the 3.0.0 release. Please refer to the smb.conf(5) man page for
146 complete descriptions of new or modified parameters.
150 <title>Removed Parameters</title>
152 <para>(Ordered Alphabetically):</para>
155 <listitem><para>admin log </para></listitem>
156 <listitem><para>alternate permissions </para></listitem>
157 <listitem><para>character set </para></listitem>
158 <listitem><para>client codepage </para></listitem>
159 <listitem><para>code page directory </para></listitem>
160 <listitem><para>coding system </para></listitem>
161 <listitem><para>domain admin group </para></listitem>
162 <listitem><para>domain guest group </para></listitem>
163 <listitem><para>force unknown acl user </para></listitem>
164 <listitem><para>nt smb support </para></listitem>
165 <listitem><para>post script </para></listitem>
166 <listitem><para>printer driver </para></listitem>
167 <listitem><para>printer driver file </para></listitem>
168 <listitem><para>printer driver location </para></listitem>
169 <listitem><para>status </para></listitem>
170 <listitem><para>strip dot </para></listitem>
171 <listitem><para>total print jobs </para></listitem>
172 <listitem><para>use rhosts </para></listitem>
173 <listitem><para>valid chars </para></listitem>
174 <listitem><para>vfs options </para></listitem>
180 <title>New Parameters</title>
182 <para>(New parameters have been grouped by function):</para>
184 <para>Remote Management</para>
187 <listitem><para>abort shutdown script </para></listitem>
188 <listitem><para>shutdown script </para></listitem>
191 <para>User and Group Account Management:</para>
194 <listitem><para>add group script </para></listitem>
195 <listitem><para>add machine script </para></listitem>
196 <listitem><para>add user to group script </para></listitem>
197 <listitem><para>algorithmic rid base </para></listitem>
198 <listitem><para>delete group script </para></listitem>
199 <listitem><para>delete user from group script </para></listitem>
200 <listitem><para>passdb backend </para></listitem>
201 <listitem><para>set primary group script </para></listitem>
204 <para>Authentication:</para>
207 <listitem><para>auth methods </para></listitem>
208 <listitem><para>realm </para></listitem>
211 <para>Protocol Options:</para>
214 <listitem><para>client lanman auth </para></listitem>
215 <listitem><para>client NTLMv2 auth </para></listitem>
216 <listitem><para>client schannel </para></listitem>
217 <listitem><para>client signing </para></listitem>
218 <listitem><para>client use spnego </para></listitem>
219 <listitem><para>disable netbios </para></listitem>
220 <listitem><para>ntlm auth </para></listitem>
221 <listitem><para>paranoid server security </para></listitem>
222 <listitem><para>server schannel </para></listitem>
223 <listitem><para>server signing </para></listitem>
224 <listitem><para>smb ports </para></listitem>
225 <listitem><para>use spnego </para></listitem>
228 <para>File Service:</para>
231 <listitem><para>get quota command </para></listitem>
232 <listitem><para>hide special files </para></listitem>
233 <listitem><para>hide unwriteable files </para></listitem>
234 <listitem><para>hostname lookups </para></listitem>
235 <listitem><para>kernel change notify </para></listitem>
236 <listitem><para>mangle prefix </para></listitem>
237 <listitem><para>map acl inherit </para></listitem>
238 <listitem><para>msdfs proxy </para></listitem>
239 <listitem><para>set quota command </para></listitem>
240 <listitem><para>use sendfile </para></listitem>
241 <listitem><para>vfs objects </para></listitem>
244 <para>Printing:</para>
247 <listitem><para>max reported print jobs </para></listitem>
251 <para>Unicode and Character Sets:</para>
254 <listitem><para>display charset </para></listitem>
255 <listitem><para>dos charset </para></listitem>
256 <listitem><para>unicode </para></listitem>
257 <listitem><para>UNIX charset </para></listitem>
260 <para>SID to UID/GID Mappings:</para>
263 <listitem><para>idmap backend </para></listitem>
264 <listitem><para>idmap gid </para></listitem>
265 <listitem><para>idmap uid </para></listitem>
266 <listitem><para>winbind enable local accounts </para></listitem>
267 <listitem><para>winbind trusted domains only </para></listitem>
268 <listitem><para>template primary group </para></listitem>
269 <listitem><para>enable rid algorithm </para></listitem>
275 <listitem><para>ldap delete dn </para></listitem>
276 <listitem><para>ldap group suffix </para></listitem>
277 <listitem><para>ldap idmap suffix </para></listitem>
278 <listitem><para>ldap machine suffix </para></listitem>
279 <listitem><para>ldap passwd sync </para></listitem>
280 <listitem><para>ldap user suffix </para></listitem>
283 <para>General Configuration:</para>
286 <listitem><para>preload modules </para></listitem>
287 <listitem><para>privatedir </para></listitem>
293 <title>Modified Parameters (Changes in Behavior):</title>
296 <listitem><para>encrypt passwords (enabled by default) </para></listitem>
297 <listitem><para>mangling method (set to hash2 by default) </para></listitem>
298 <listitem><para>passwd chat </para></listitem>
299 <listitem><para>passwd program </para></listitem>
300 <listitem><para>password server </para></listitem>
301 <listitem><para>restrict anonymous (integer value) </para></listitem>
302 <listitem><para>security (new ads value) </para></listitem>
303 <listitem><para>strict locking (enabled by default) </para></listitem>
304 <listitem><para>winbind cache time (increased to 5 minutes) </para></listitem>
305 <listitem><para>winbind uid (deprecated in favor of idmap uid) </para></listitem>
306 <listitem><para>winbind gid (deprecated in favor of idmap gid) </para></listitem>
314 <title>New Functionality</title>
317 <title>Databases</title>
320 This section contains brief descriptions of any new databases
321 introduced in Samba-3. Please remember to backup your existing
322 ${lock directory}/*tdb before upgrading to Samba-3. Samba will
323 upgrade databases as they are opened (if necessary), but downgrading
324 from 3.0 to 2.2 is an unsupported path.
328 The new tdb files are described in <link linkend="tdbfiledesc">the next table</link>.
332 <table frame='all' id="tdbfiledesc"><title>TDB File Descriptions</title>
334 <colspec align="left"/>
335 <colspec align="justify" colwidth="1*"/>
336 <colspec align="left"/>
339 <entry align="left">Name</entry>
340 <entry align="justify">Description</entry>
341 <entry align="center">Backup?</entry>
346 <entry>account_policy</entry>
347 <entry>User policy settings</entry>
351 <entry>gencache</entry>
352 <entry>Generic caching db</entry>
356 <entry>group_mapping</entry>
357 <entry><para>Mapping table from Windows groups/SID to UNIX groups</para></entry>
362 <entry><para>new ID map table from SIDS to UNIX UIDs/GIDs</para></entry>
366 <entry>namecache</entry>
367 <entry>Name resolution cache entries</entry>
371 <entry>netlogon_unigrp</entry>
372 <entry><para>Cache of universal group membership obtained when operating
373 as a member of a Windows domain</para></entry>
377 <entry>printing/*.tdb</entry>
378 <entry><para>Cached output from `lpq command' created on a per print
379 service basis</para></entry>
384 <entry>registry</entry>
385 <entry><para>Read-only Samba registry skeleton that provides support for
386 exporting various db tables via the winreg RPCs</para></entry>
396 <title>Changes in Behavior</title>
399 The following issues are known changes in behavior between Samba-2.2 and
400 Samba-3 that may affect certain installations of Samba.
405 When operating as a member of a Windows domain, Samba-2.2 would
406 map any users authenticated by the remote DC to the <quote>guest account</quote>
407 if a uid could not be obtained via the getpwnam() call. Samba-3
408 rejects the connection as <?latex \linebreak ?>NT_STATUS_LOGON_FAILURE. There is no
409 current work around to re-establish the Samba-2.2 behavior.
413 When adding machines to a Samba-2.2 controlled domain, the
414 <quote>add user script</quote> was used to create the UNIX identity of the
415 Machine Trust Account. Samba-3 introduces a new <quote>add machine
416 script</quote> that must be specified for this purpose. Samba-3 will
417 not fall back to using the <quote>add user script</quote> in the absence of
418 an <quote>add machine script</quote>.
425 <title>Passdb Backends and Authentication</title>
428 There have been a few new changes that Samba administrators should be
429 aware of when moving to Samba-3.
434 Encrypted passwords have been enabled by default in order to
435 interoperate better with out-of-the-box Windows client
436 installations. This does mean that either (a) a Samba account
437 must be created for each user, or (b) <quote>encrypt passwords = no</quote>
438 must be explicitly defined in &smb.conf;.
442 Inclusion of new <smbconfoption><name>security</name><value>ads</value></smbconfoption> option for integration
443 with an Active Directory domain using the native Windows Kerberos 5 and LDAP protocols.
448 Samba-3 also includes the possibility of setting up chains
449 of authentication methods
450 (<smbconfoption><name>auth methods</name></smbconfoption>) and account
452 (<smbconfoption><name>passdb backend</name></smbconfoption>).
453 Please refer to the &smb.conf;
454 man page and <link linkend="passdb">Account Information Databases</link>, for details. While both parameters assume sane default
455 values, it is likely that you will need to understand what the
456 values actually mean in order to ensure Samba operates correctly.
460 <indexterm><primary>pdbedit</primary></indexterm>
461 Certain functions of the <command>smbpasswd</command> tool have been split between the
462 new <command>smbpasswd</command> utility, the <command>net</command> tool and the new <command>pdbedit</command>
463 utility. See the respective man pages for details.
472 This section outlines the new features effecting Samba/LDAP integration.
476 <title>New Schema</title>
479 A new object class (sambaSamAccount) has been introduced to replace
480 the old sambaAccount. This change aids us in the renaming of attributes
481 to prevent clashes with attributes from other vendors. There is a
482 conversion script (examples/LDAP/convertSambaAccount) to modify an LDIF
483 file to the new schema.
490 &prompt;ldapsearch .... -LLL -b "ou=people,dc=..." > old.ldif
491 &prompt;convertSambaAccount --sid <DOM SID> --input old.ldif --output new.ldif
495 The <DOM SID> can be obtained by running
497 &prompt;<userinput>net getlocalsid <DOMAINNAME></userinput>
499 on the Samba PDC as root.
503 The old sambaAccount schema may still be used by specifying the
504 <parameter>ldapsam_compat</parameter> passdb backend. However, the sambaAccount and
505 associated attributes have been moved to the historical section of
506 the schema file and must be uncommented before use if needed.
507 The Samba-2.2 object class declaration for a sambaAccount has not changed
508 in the Samba-3 samba.schema file.
512 Other new object classes and their uses include:
517 sambaDomain &smbmdash; domain information used to allocate RIDs
518 for users and groups as necessary. The attributes are added
519 in <quote>ldap suffix</quote> directory entry automatically if
520 an idmap UID/GID range has been set and the <quote>ldapsam</quote>
521 passdb backend has been selected.
525 sambaGroupMapping &smbmdash; an object representing the
526 relationship between a posixGroup and a Windows
527 group/SID. These entries are stored in the <quote>ldap
528 group suffix</quote> and managed by the <quote>net groupmap</quote> command.
532 sambaUNIXIdPool &smbmdash; created in the <quote>ldap idmap suffix</quote> entry
533 automatically and contains the next available <quote>idmap UID</quote> and
534 <quote>idmap GID</quote>.
538 sambaIdmapEntry &smbmdash; object storing a mapping between a
539 SID and a UNIX UID/GID. These objects are created by the
540 idmap_ldap module as needed.
547 <title>New Suffix for Searching</title>
550 The following new smb.conf parameters have been added to aid in directing
551 certain LDAP queries when <parameter>passdb backend = ldapsam://...</parameter> has been
556 <listitem><para>ldap suffix &smbmdash; used to search for user and computer accounts.</para></listitem>
557 <listitem><para>ldap user suffix &smbmdash; used to store user accounts.</para></listitem>
558 <listitem><para>ldap machine suffix &smbmdash; used to store Machine Trust Accounts.</para></listitem>
559 <listitem><para>ldap group suffix &smbmdash; location of posixGroup/sambaGroupMapping entries.</para></listitem>
560 <listitem><para>ldap idmap suffix &smbmdash; location of sambaIdmapEntry objects.</para></listitem>
564 If an <parameter>ldap suffix</parameter> is defined, it will be appended to all of the
565 remaining sub-suffix parameters. In this case, the order of the suffix
566 listings in smb.conf is important. Always place the <parameter>ldap suffix</parameter> first
571 Due to a limitation in Samba's &smb.conf; parsing, you should not surround
572 the DNs with quotation marks.
578 <title>IdMap LDAP Support</title>
581 Samba-3 supports an ldap backend for the idmap subsystem. The
582 following options inform Samba that the idmap table should be
583 stored on the directory server onterose in the "ou=idmap,dc=quenya,dc=org" partition.
587 <smbconfsection>[global]</smbconfsection>
589 <smbconfoption><name>idmap backend</name><value>ldap:ldap://onterose/</value></smbconfoption>
590 <smbconfoption><name>ldap idmap suffix</name><value>ou=idmap,dc=quenya,dc=org</value></smbconfoption>
591 <smbconfoption><name>idmap uid</name><value>40000-50000</value></smbconfoption>
592 <smbconfoption><name>idmap gid</name><value>40000-50000</value></smbconfoption>
596 This configuration allows Winbind installations on multiple servers to
597 share a UID/GID number space, thus avoiding the interoperability problems
598 with NFS that were present in Samba-2.2.