docs/docbook/projdoc/upgrading-to-3.0.xml

   1 <chapter id="upgrading-to-3.0">
   2 <chapterinfo>
   3         &author.jelmer;
   4         &author.jht;
   5         &author.jerry;
   6         <pubdate>June 30, 2003</pubdate>
   7 </chapterinfo>
   8
   9 <title>Upgrading from Samba-2.x to Samba-3.0.0</title>
  10
  11
  12 <sect1>
  13 <title>New Features in Samba-3</title>
  14
  15 <para>
  16 Major new features:
  17 </para>
  18
  19 <orderedlist>
  20         <listitem><para>
  21         Active Directory support. This release is able to join a ADS realm
  22         as a member server and authenticate users using LDAP/kerberos.
  23         </para></listitem>
  24
  25         <listitem><para>
  26         Unicode support. Samba will now negotiate UNICODE on the wire and
  27         internally there is now a much better infrastructure for multi-byte
  28         and UNICODE character sets.
  29         </para></listitem>
  30
  31         <listitem><para>
  32         New authentication system. The internal authentication system has
  33         been almost completely rewritten. Most of the changes are internal,
  34         but the new auth system is also very configurable.
  35         </para></listitem>
  36
  37         <listitem><para>
  38         New filename mangling system. The filename mangling system has been
  39         completely rewritten. An internal database now stores mangling maps
  40         persistently. This needs lots of testing.
  41         </para></listitem>
  42
  43         <listitem><para>
  44         New "net" command. A new "net" command has been added. It is
  45         somewhat similar to the "net" command in windows. Eventually we
  46         plan to replace a bunch of other utilities (such as smbpasswd)
  47         with subcommands in "net", at the moment only a few things are
  48         implemented.
  49         </para></listitem>
  50
  51         <listitem><para>
  52         Samba now negotiates NT-style status32 codes on the wire. This
  53         improves error handling a lot.
  54         </para></listitem>
  55
  56         <listitem><para>
  57         Better Windows 2000/XP/2003 printing support including publishing
  58         printer attributes in active directory
  59         </para></listitem>
  60
  61         <listitem><para>
  62         New loadable RPC modules
  63         </para></listitem>
  64
  65         <listitem><para>
  66         New dual-daemon winbindd support (-B) for better performance
  67         </para></listitem>
  68
  69         <listitem><para>
  70         Support for migrating from a Windows NT 4.0 domain to a Samba
  71         domain and maintaining user, group and domain SIDs
  72         </para></listitem>
  73
  74         <listitem><para>
  75         Support for establishing trust relationships with Windows NT 4.0
  76         domain controllers
  77         </para></listitem>
  78
  79         <listitem><para>
  80         Initial support for a distributed Winbind architecture using
  81         an LDAP directory for storing SID to uid/gid mappings
  82         </para></listitem>
  83
  84         <listitem><para>
  85         Major updates to the Samba documentation tree.
  86         </para></listitem>
  87 </orderedlist>
  88 <para>
  89 Plus lots of other improvements!
  90 </para>
  91
  92 </sect1>
  93
  94 <sect1>
  95 <title>Configuration Parameter Changes</title>
  96
  97 <para>
  98 This section contains a brief listing of changes to smb.conf options
  99 in the 3.0.0 release.  Please refer to the smb.conf(5) man page for
 100 complete descriptions of new or modified parameters.
 101 </para>
 102
 103 <sect2>
 104 <title>Removed Parameters</title>
 105
 106 <para>(order alphabetically):</para>
 107
 108 <itemizedlist>
 109         <listitem><para>admin log </para></listitem>
 110         <listitem><para>alternate permissions </para></listitem>
 111         <listitem><para>character set </para></listitem>
 112         <listitem><para>client codepage </para></listitem>
 113         <listitem><para>code page directory </para></listitem>
 114         <listitem><para>coding system </para></listitem>
 115         <listitem><para>domain admin group </para></listitem>
 116         <listitem><para>domain guest group </para></listitem>
 117         <listitem><para>force unknown acl user </para></listitem>
 118         <listitem><para>nt smb support </para></listitem>
 119         <listitem><para>post script </para></listitem>
 120         <listitem><para>printer driver </para></listitem>
 121         <listitem><para>printer driver file </para></listitem>
 122         <listitem><para>printer driver location </para></listitem>
 123         <listitem><para>status </para></listitem>
 124         <listitem><para>total print jobs </para></listitem>
 125         <listitem><para>use rhosts </para></listitem>
 126         <listitem><para>valid chars </para></listitem>
 127         <listitem><para>vfs options </para></listitem>
 128 </itemizedlist>
 129
 130 </sect2>
 131
 132 <sect2>
 133 <title>New Parameters</title>
 134
 135 <para>(new parameters have been grouped by function):</para>
 136
 137 <para>Remote management</para>
 138
 139 <itemizedlist>
 140         <listitem><para>abort shutdown script </para></listitem>
 141         <listitem><para>shutdown script </para></listitem>
 142 </itemizedlist>
 143
 144 <para>User and Group Account Management</para>
 145
 146 <itemizedlist>
 147         <listitem><para>add group script </para></listitem>
 148         <listitem><para>add machine script </para></listitem>
 149         <listitem><para>add user to group script </para></listitem>
 150         <listitem><para>algorithmic rid base </para></listitem>
 151         <listitem><para>delete group script </para></listitem>
 152         <listitem><para>delete user from group script </para></listitem>
 153         <listitem><para>passdb backend </para></listitem>
 154         <listitem><para>set primary group script </para></listitem>
 155 </itemizedlist>
 156
 157 <para>Authentication</para>
 158
 159 <itemizedlist>
 160         <listitem><para>auth methods </para></listitem>
 161         <listitem><para>ads server </para></listitem>
 162         <listitem><para>realm </para></listitem>
 163 </itemizedlist>
 164
 165 <para>Protocol Options</para>
 166
 167 <itemizedlist>
 168         <listitem><para>client lanman auth </para></listitem>
 169         <listitem><para>client NTLMv2 auth </para></listitem>
 170         <listitem><para>client schannel </para></listitem>
 171         <listitem><para>client signing </para></listitem>
 172         <listitem><para>client use spnego </para></listitem>
 173         <listitem><para>disable netbios </para></listitem>
 174         <listitem><para>ntlm auth </para></listitem>
 175         <listitem><para>paranoid server security </para></listitem>
 176         <listitem><para>server schannel </para></listitem>
 177         <listitem><para>smb ports </para></listitem>
 178         <listitem><para>use spnego </para></listitem>
 179 </itemizedlist>
 180
 181 <para>File Service</para>
 182
 183 <itemizedlist>
 184         <listitem><para>get quota command </para></listitem>
 185         <listitem><para>hide special files </para></listitem>
 186         <listitem><para>hide unwriteable files </para></listitem>
 187         <listitem><para>hostname lookups </para></listitem>
 188         <listitem><para>kernel change notify </para></listitem>
 189         <listitem><para>mangle prefix </para></listitem>
 190         <listitem><para>msdfs proxy </para></listitem>
 191         <listitem><para>set quota command </para></listitem>
 192         <listitem><para>use sendfile </para></listitem>
 193         <listitem><para>vfs objects </para></listitem>
 194 </itemizedlist>
 195
 196 <para>Printing</para>
 197
 198 <itemizedlist>
 199         <listitem><para>max reported print jobs </para></listitem>
 200 </itemizedlist>
 201
 202
 203 <para>UNICODE and Character Sets</para>
 204
 205 <itemizedlist>
 206         <listitem><para>display charset </para></listitem>
 207         <listitem><para>dos charset </para></listitem>
 208         <listitem><para>unicode </para></listitem>
 209         <listitem><para>unix charset </para></listitem>
 210 </itemizedlist>
 211
 212 <para>SID to uid/gid Mappings</para>
 213
 214 <itemizedlist>
 215         <listitem><para>idmap backend </para></listitem>
 216         <listitem><para>idmap gid </para></listitem>
 217         <listitem><para>idmap only </para></listitem>
 218         <listitem><para>idmap uid </para></listitem>
 219 </itemizedlist>
 220
 221 <para>LDAP</para>
 222
 223 <itemizedlist>
 224         <listitem><para>ldap delete dn </para></listitem>
 225         <listitem><para>ldap group suffix </para></listitem>
 226         <listitem><para>ldap idmap suffix </para></listitem>
 227         <listitem><para>ldap machine suffix </para></listitem>
 228         <listitem><para>ldap passwd sync </para></listitem>
 229         <listitem><para>ldap trust ids </para></listitem>
 230         <listitem><para>ldap user suffix </para></listitem>
 231 </itemizedlist>
 232
 233 <para>General Configuration</para>
 234
 235 <itemizedlist>
 236         <listitem><para>preload modules </para></listitem>
 237         <listitem><para>privatedir </para></listitem>
 238 </itemizedlist>
 239
 240 </sect2>
 241
 242 <sect2>
 243 <title>Modified Parameters (changes in behavior):</title>
 244
 245 <itemizedlist>
 246         <listitem><para>encrypt passwords (enabled by default) </para></listitem>
 247         <listitem><para>mangling method (set to 'hash2' by default) </para></listitem>
 248         <listitem><para>passwd chat </para></listitem>
 249         <listitem><para>passwd program </para></listitem>
 250         <listitem><para>restrict anonymous (integer value) </para></listitem>
 251         <listitem><para>security (new 'ads' value) </para></listitem>
 252         <listitem><para>strict locking (enabled by default) </para></listitem>
 253         <listitem><para>winbind cache time (increased to 5 minutes) </para></listitem>
 254         <listitem><para>winbind uid (deprecated in favor of 'idmap uid') </para></listitem>
 255         <listitem><para>winbind gid (deprecated in favor of 'idmap gid') </para></listitem>
 256 </itemizedlist>
 257
 258 </sect2>
 259
 260 </sect1>
 261
 262 <sect1>
 263 <title>New Functionality</title>
 264
 265         <sect2>
 266         <title>Databases</title>
 267
 268         <para>
 269         This section contains brief descriptions of any new databases
 270         introduced in Samba 3.0.  Please remember to backup your existing
 271         ${lock directory}/*tdb before upgrading to Samba 3.0.  Samba will
 272         upgrade databases as they are opened (if necessary), but downgrading
 273         from 3.0 to 2.2 is an unsupported path.
 274         </para>
 275
 276
 277         <table frame='all'><title>TDB File Descriptions</title>
 278         <tgroup cols='3'>
 279                         <colspec align="left"/>
 280                         <colspec align="justify"/>
 281                         <colspec align="left"/>
 282                 <thead>
 283                 <row>
 284                         <entry align="left">Name</entry>
 285                         <entry align="justify">Description</entry>
 286                         <entry align="center">Backup?</entry>
 287                 </row>
 288                 </thead>
 289                 <tbody>
 290                 <row>
 291                         <entry>account_policy</entry>
 292                         <entry>User policy settings</entry>
 293                         <entry>yes</entry>
 294                 </row>
 295                 <row>
 296                         <entry>gencache</entry>
 297                         <entry>Generic caching db</entry>
 298                         <entry>no</entry>
 299                 </row>
 300                 <row>
 301                         <entry>group_mapping</entry>
 302                         <entry><para>Mapping table from Windows groups/SID to unix groups</para></entry>
 303                         <entry>yes</entry>
 304                 </row>
 305                 <row>
 306                         <entry>idmap</entry>
 307                         <entry><para>new ID map table from SIDS to UNIX uids/gids</para></entry>
 308                         <entry>yes</entry>
 309                 </row>
 310                 <row>
 311                         <entry>namecache</entry>
 312                         <entry>Name resolution cache entries</entry>
 313                         <entry>no</entry>
 314                 </row>
 315                 <row>
 316                         <entry>netlogon_unigrp</entry>
 317                         <entry><para>Cache of universal group membership obtained when operating
 318                                 as a member of a Windows domain</para></entry>
 319                         <entry>no</entry>
 320                 </row>
 321                 <row>
 322                         <entry>printing/*.tdb</entry>
 323                         <entry><para>Cached output from 'lpq command' created on a per print
 324                                 service basis</para></entry>
 325                         <entry>no</entry>
 326                 </row>
 327                 <row>
 328
 329                         <entry>registry</entry>
 330                         <entry><para>Read-only samba registry skeleton that provides support for
 331                                 exporting various db tables via the winreg RPCs</para></entry>
 332                         <entry>no</entry>
 333                 </row>
 334                 </tbody>
 335         </tgroup>
 336         </table>
 337
 338         </sect2>
 339
 340         <sect2>
 341         <title>Changes in Behavior</title>
 342
 343         <para>
 344         The following issues are known changes in behavior between Samba 2.2 and
 345         Samba 3.0 that may affect certain installations of Samba.
 346         </para>
 347
 348         <orderedlist>
 349                 <listitem><para>
 350                 When operating as a member of a Windows domain, Samba 2.2 would
 351                 map any users authenticated by the remote DC to the 'guest account'
 352                 if a uid could not be obtained via the getpwnam() call.  Samba 3.0
 353                 rejects the connection as NT_STATUS_LOGON_FAILURE.  There is no
 354                 current work around to re-establish the 2.2 behavior.
 355                 </para></listitem>
 356
 357                 <listitem><para>
 358                 When adding machines to a Samba 2.2 controlled domain, the
 359                 'add user script' was used to create the UNIX identity of the
 360                 machine trust account.  Samba 3.0 introduces a new 'add machine
 361                 script' that must be specified for this purpose.  Samba 3.0 will
 362                 not fall back to using the 'add user script' in the absence of
 363                 an 'add machine script'
 364                 </para></listitem>
 365         </orderedlist>
 366
 367         </sect2>
 368
 369         <sect2>
 370         <title>Charsets</title>
 371
 372         <para>
 373         You might experience problems with special characters when communicating with old DOS
 374         clients. Codepage support has changed in samba 3.0. Read the chapter
 375         <link linkend="unicode">Unicode support</link> for details.
 376         </para>
 377
 378         </sect2>
 379
 380         <sect2>
 381         <title>Passdb Backends and Authentication</title>
 382
 383         <para>
 384         There have been a few new changes that Samba administrators should be
 385         aware of when moving to Samba 3.0.
 386         </para>
 387
 388         <orderedlist>
 389                 <listitem><para>
 390                 Encrypted passwords have been enabled by default in order to
 391                 inter-operate better with out-of-the-box Windows client
 392                 installations.  This does mean that either (a) a samba account
 393                 must be created for each user, or (b) 'encrypt passwords = no'
 394                 must be explicitly defined in smb.conf.
 395                 </para></listitem>
 396
 397                 <listitem><para>
 398                                 Inclusion of new <smbconfoption><name>security</name><value>ads</value></smbconfoption> option for integration
 399                 with an Active Directory domain using the native Windows
 400                 Kerberos 5 and LDAP protocols.
 401                 </para></listitem>
 402         </orderedlist>
 403
 404         <para>
 405         Samba 3.0 also includes the possibility of setting up chains
 406         of authentication methods
 407         (<smbconfoption><name>auth methods</name></smbconfoption>) and account
 408         storage backends
 409         (<smbconfoption><name>passdb backend</name></smbconfoption>).
 410         Please refer to the &smb.conf;
 411         man page and <link linkend="passdb"/> for details.  While both parameters assume sane default
 412         values, it is likely that you will need to understand what the
 413         values actually mean in order to ensure Samba operates correctly.
 414         </para>
 415
 416         <para>
 417         Certain functions of the smbpasswd(8) tool have been split between the
 418         new smbpasswd(8) utility, the net(8) tool, and the new pdbedit(8)
 419         utility.  See the respective man pages for details.
 420         </para>
 421
 422         </sect2>
 423
 424         <sect2>
 425         <title>Charsets</title>
 426
 427         <para>
 428         You might experience problems with special characters when communicating with old DOS
 429         clients. Codepage support has changed in samba 3.0. Read the chapter
 430         <link linkend="unicode">Unicode support</link> for details.
 431         </para>
 432
 433         </sect2>
 434
 435         <sect2>
 436         <title>LDAP</title>
 437
 438         <para>
 439         This section outlines the new features affecting Samba / LDAP integration.
 440         </para>
 441
 442                 <sect3>
 443                 <title>New Schema</title>
 444
 445                 <para>
 446                 A new object class (sambaSamAccount) has been introduced to replace
 447                 the old sambaAccount.  This change aids us in the renaming of attributes
 448                 to prevent clashes with attributes from other vendors.  There is a
 449                 conversion script (examples/LDAP/convertSambaAccount) to modify and LDIF
 450                 file to the new schema.
 451                 </para>
 452
 453                 <para>
 454                         Example:
 455                 </para>
 456                 <para><screen>
 457                 &prompt;ldapsearch .... -b "ou=people,dc=..." &gt; old.ldif
 458                 &prompt;convertSambaAccount &lt;DOM SID&gt; old.ldif new.ldif
 459                 </screen></para>
 460
 461                 <para>
 462                 The &lt;DOM SID&gt; can be obtained by running 'net getlocalsid &lt;DOMAINNAME&gt;
 463                 on the Samba PDC as root.
 464                 </para>
 465
 466                 <para>
 467                 The old sambaAccount schema may still be used by specifying the
 468                 "ldapsam_compat" passdb backend.  However, the sambaAccount and
 469                 associated attributes have been moved to the historical section of
 470                 the schema file and must be uncommented before use if needed.
 471                 The 2.2 object class declaration for a sambaAccount has not changed
 472                 in the 3.0 samba.schema file.
 473                 </para>
 474
 475                 <para>
 476                 Other new object classes and their uses include:
 477                 </para>
 478
 479                 <itemizedlist>
 480                         <listitem><para>
 481                         sambaDomain - domain information used to allocate rids
 482                         for users and groups as necessary.  The attributes are added
 483                         in 'ldap suffix' directory entry automatically if
 484                         an idmap uid/gid range has been set and the 'ldapsam'
 485                         passdb backend has been selected.
 486                         </para></listitem>
 487
 488                         <listitem><para>
 489                         sambaGroupMapping - an object representing the
 490                         relationship between a posixGroup and a Windows
 491                         group/SID.  These entries are stored in the 'ldap
 492                         group suffix' and managed by the 'net groupmap' command.
 493                         </para></listitem>
 494
 495                         <listitem><para>
 496                         sambaUnixIdPool - created in the 'ldap idmap suffix' entry
 497                         automatically and contains the next available 'idmap uid' and
 498                         'idmap gid'
 499                         </para></listitem>
 500
 501                         <listitem><para>
 502                         sambaIdmapEntry - object storing a mapping between a
 503                         SID and a UNIX uid/gid.  These objects are created by the
 504                         idmap_ldap module as needed.
 505                         </para></listitem>
 506                 </itemizedlist>
 507
 508                 </sect3>
 509
 510                 <sect3>
 511                 <title>New Suffix for Searching</title>
 512
 513                 <para>
 514                 The following new smb.conf parameters have been added to aid in directing
 515                 certain LDAP queries when 'passdb backend = ldapsam://...' has been
 516                 specified.
 517                 </para>
 518
 519                 <itemizedlist>
 520                         <listitem><para>ldap suffix         - used to search for user and computer accounts</para></listitem>
 521                         <listitem><para>ldap user suffix    - used to store user accounts</para></listitem>
 522                         <listitem><para>ldap machine suffix - used to store machine trust accounts</para></listitem>
 523                         <listitem><para>ldap group suffix   - location of posixGroup/sambaGroupMapping entries</para></listitem>
 524                         <listitem><para>ldap idmap suffix   - location of sambaIdmapEntry objects</para></listitem>
 525                 </itemizedlist>
 526
 527                 <para>
 528                 If an 'ldap suffix' is defined, it will be appended to all of the
 529                 remaining sub-suffix parameters.  In this case, the order of the suffix
 530                 listings in smb.conf is important.  Always place the 'ldap suffix' first
 531                 in the list.
 532                 </para>
 533
 534                 <para>
 535                 Due to a limitation in Samba's smb.conf parsing, you should not surround
 536                 the DN's with quotation marks.
 537                 </para>
 538
 539                 </sect3>
 540
 541                 <sect3>
 542                 <title>IdMap LDAP support</title>
 543
 544                 <para>
 545                 Samba 3.0 supports an ldap backend for the idmap subsystem.  The
 546                 following options would inform Samba that the idmap table should be
 547                 stored on the directory server onterose in the "ou=idmap,dc=plainjoe,
 548                 dc=org" partition.
 549                 </para>
 550
 551                 <smbconfblock>
 552                 <smbconfsection>[global]</smbconfsection>
 553                 <member>...</member>
 554                 <smbconfoption><name>idmap backend</name><value>ldap:ldap://onterose/</value></smbconfoption>
 555                 <smbconfoption><name>ldap idmap suffix</name><value>ou=idmap,dc=plainjoe,dc=org</value></smbconfoption>
 556                 <smbconfoption><name>idmap uid</name><value>40000-50000</value></smbconfoption>
 557                 <smbconfoption><name>idmap gid</name><value>40000-50000</value></smbconfoption>
 558                 </smbconfblock>
 559
 560                 <para>
 561                 This configuration allows winbind installations on multiple servers to
 562                 share a uid/gid number space, thus avoiding the interoperability problems
 563                 with NFS that were present in Samba 2.2.
 564                 </para>
 565
 566                 </sect3>
 567
 568         </sect2>
 569
 570 </sect1>
 571
 572 </chapter>