1 <?xml version="1.0" encoding="iso-8859-1"?>
2 <!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
3 <chapter id="upgrades">
4 <title>Updating Samba-3</title>
7 <indexterm><primary>migrate</primary></indexterm>
8 <indexterm><primary>install</primary></indexterm>
9 It was a little difficult to select an appropriate title for this chapter.
10 From email messages on the Samba mailing lists it is clear that many people
11 consider the updating and upgrading of Samba to be a migration matter. Others
12 talk about migrating Samba servers when in fact the issue at hand is one of
13 installing a new Samba server to replace an older existing Samba server.
17 <indexterm><primary>smbpasswd</primary></indexterm>
18 <indexterm><primary>passdb backend</primary></indexterm>
19 There has also been much talk about migration of Samba-3 from an smbpasswd
20 passdb backend to the use of the tdbsam or ldapsam facilities that are new
25 Clearly, there is not a great deal of clarity in the terminology that various
26 people apply to these modes by which Samba servers are updated. This is further
27 highlighted by an email posting that included the following neat remark:
31 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>vampire</tertiary></indexterm>
32 I like the <quote>net rpc vampire</quote> on NT4, but that to my surprise does
33 not seem to work against a Samba PDC and, if addressed in the Samba to Samba
34 context in either book, I could not find it.
38 <indexterm><primary>contributions</primary></indexterm>
39 So in response to the significant request for these situations to be better
40 documented this chapter has now been added. User contributions and documentation
41 of real-world experiences will be a most welcome addition to this chapter.
45 <title>Introduction</title>
48 <indexterm><primary>update</primary></indexterm>
49 <indexterm><primary>upgrade</primary></indexterm>
50 <indexterm><primary>frustration</primary></indexterm>
51 A Windows network administrator explained in an email what changes he was
52 planning to make and and followed with the question: <quote>Anyone done this before?</quote>.
53 Many of us have upgraded and updated Samba without incident. Others have
54 experienced much pain and user frustration. So it is to be hoped that the
55 notes in this chapter will make a positive difference by assuring that
56 someone will be saved a lot of discomfort.
60 Before anyone commences an upgrade or an update of Samba the one cardinal
61 rule that must be observed is: Backup all Samba configuration files in
62 case it is necessary to revert to the old version. Even if you do not like
63 this precautionary step, users will punish an administrator who
64 fails to take adequate steps to avoid situations that may inflict lost
65 productivity on a user.
69 <indexterm><primary>configuration files</primary></indexterm>
70 <indexterm><primary>down-grade</primary></indexterm>
71 Samba makes it possible to upgrade and update configuration files, but it
72 is not possible to downgrade the configuration files. Please ensure that
73 all configuration and control files are backed up to permit a down-grade
74 in the rare event that this may be necessary.
79 <indexterm><primary>adequate precautions</primary></indexterm>
80 <indexterm><primary>precaution</primary></indexterm>
81 It is prudent also to backup all data files on the server before attempting
82 to perform a major upgrade. Many administrators have experienced the consequences
83 of failure to take adequate precautions. So what is adequate? That is simple!
84 If data is lost during an upgrade or and update and it can not be restored
85 the precautions take were inadequate. If a backup was not needed, but was available,
86 precaution was on the side of the victor.
90 <title>Cautions and Notes</title>
93 Someone once said, <quote>It is good to be sorry, but better never to need to be!</quote>
94 These are wise words of advice to those contemplating a Samba upgrade or update.
98 <indexterm><primary>update</primary></indexterm>
99 <indexterm><primary>upgrade</primary></indexterm>
100 <indexterm><primary>generation</primary></indexterm>
101 This is as good a time as any to define the terms <constant>upgrade</constant> and
102 <constant>update</constant>. The term <constant>upgrade</constant> is used to refer to
103 the installation of a version of Samba that is a whole generation or more ahead of
104 that which is installed. Generations are indicated by the first digit of the version
105 number. So far Samba has been released in generations 1.x, 2.x, 3.x and currently 4.0
110 <indexterm><primary>generation</primary></indexterm>
111 The term <constant>update</constant> is used to refer to a minor version number installation
112 in place of one of the same generation. For example, updating from Samba 3.0.10 to 3.0.14
113 is an update. The move from Samba 2.0.7 to 3.0.14 is an upgrade.
117 <indexterm><primary>functional differences</primary></indexterm>
118 While the use of these terms is an exercise in semantics, what needs to be realized
119 is that there are major functional differences between a Samba 2.x release and a Samba
120 3.0.x release. Such differences may require a significantly different approach to
121 solving the same networking challenge and generally requires careful review of the
122 latest documentation to identify precisely how the new installation may need to be
123 modified to preserve prior functionality.
127 There is an old axiom that says, <quote>The greater the volume of the documentation
128 the greater the risk that no-one will read it, but where there is no documentation
129 no-one can read it!</quote>. While true, some documentation is an evil necessity.
130 It is to be hoped that this update to the documentation will avoid both extremes.
134 <title>Security Identifiers (SIDs)</title>
137 <indexterm><primary>Windows</primary><secondary>NT</secondary></indexterm>
138 <indexterm><primary>OS/2</primary></indexterm>
139 <indexterm><primary>DOS</primary></indexterm>
140 <indexterm><primary>SID</primary></indexterm>
141 <indexterm><primary>networking</primary><secondary>client</secondary></indexterm>
142 <indexterm><primary>security</primary><secondary>identifier</secondary></indexterm>
143 Before the days of Windows NT and OS/2 every Windows and DOS networking client
144 that used the SMB protocols was an entirely autonomous entity. There was no concept
145 of a security identifier for a machine or a user outside of the username, the
146 machine name, and the workgroup name. In actual fact, these were not security identifiers
147 in the same context as the way that the SID is used since the development of
152 <indexterm><primary>SessionSetUpAndX</primary></indexterm>
153 <indexterm><primary>SMB</primary></indexterm>
154 <indexterm><primary>CIFS</primary></indexterm>
155 <indexterm><primary>SID</primary></indexterm>
156 <indexterm><primary>username</primary></indexterm>
157 <indexterm><primary>Windows</primary><secondary>client</secondary></indexterm>
158 Versions of Samba prior to 1.9 did not make use of a SID, instead they make exclusive use
159 of the username that is embedded in the SessionSetUpAndX component of the connection
160 setup process between a Windows client and an SMB/CIFS server.
164 <indexterm><primary>MACHINE.SID</primary></indexterm>
165 <indexterm><primary>rpc</primary></indexterm>
166 <indexterm><primary>security</primary></indexterm>
167 Around November 1997 support was added to Samba-1.9 to handle the Windows security
168 rpc based protocols that implemented support for Samba to store a machine SID. This
169 information was stored in a file called <filename>MACHINE.SID.</filename>
173 <indexterm><primary>machine</primary></indexterm>
174 <indexterm><primary>SID</primary></indexterm>
175 <indexterm><primary>secrets.tdb</primary></indexterm>
176 Within the life time of the early Samba 2.x series the machine SID information was
177 relocated into a tdb file called <filename>secrets.tdb</filename>, which is where is
178 is still located in Samba 3.0.x along with other information that pertains to the
179 local machine and its role within a domain security context.
183 <indexterm><primary>server</primary><secondary>stand-alone</secondary></indexterm>
184 <indexterm><primary>server</primary><secondary>domain member</secondary></indexterm>
185 <indexterm><primary>DMS</primary></indexterm>
186 <indexterm><primary>SAS</primary></indexterm>
187 There are two types of SID, those pertaining to the machine itself and the domain to
188 which it may belong, and those pertaining to users and groups within the security
189 context of the local machine (in the case of stand-alone servers (SAS) and domain member
194 <indexterm><primary>smbd</primary></indexterm>
195 <indexterm><primary>workgroup</primary></indexterm>
196 <indexterm><primary>hostname</primary></indexterm>
197 <indexterm><primary>daemon</primary></indexterm>
198 <indexterm><primary>SID</primary></indexterm>
199 <indexterm><primary>secrets.tdb</primary></indexterm>
200 When the Samba <command>smbd</command> daemon is first started, if the <filename>secrets.tdb</filename>
201 file does not exist it is created at the first client connection attempt. If this file does
202 exist, <command>smbd</command> checks that there is a machine SID (if it is a domain controller
203 it searches for the domain SID). If <command>smbd</command> does not find one for the current
204 name of the machine or for the current name of the workgroup a new SID will be generated and
205 then written to the <filename>secrets.tdb</filename> file. The SID is generated in a non-determinative
206 manner. This means that each time it is generated for a particular combination of machine name
207 (hostname) and domain name (workgroup) it will be different.
211 <indexterm><primary>ACL</primary></indexterm>
212 The SID is the key used by MS Windows networking for all networking operations. This means
213 that when the machine or domain SID changes all security encoded objects such as profiles
214 and ACLs may become unusable.
218 It is of paramount importance that the machine and domain SID must be backed up so that in
219 the event of a change of hostname (machine name) or domain name (workgroup) the SID can
220 be restored to its previous value.
224 <indexterm><primary>domain controller</primary></indexterm>
225 <indexterm><primary>PDC</primary></indexterm>
226 <indexterm><primary>BDC</primary></indexterm>
227 <indexterm><primary>domain SID</primary></indexterm>
228 <indexterm><primary>hostname</primary></indexterm>
229 <indexterm><primary>computer name</primary></indexterm>
230 <indexterm><primary>netbios name</primary></indexterm>
231 <indexterm><primary>stand-alone server</primary></indexterm>
232 <indexterm><primary>SAS</primary></indexterm>
233 <indexterm><primary>SID</primary></indexterm>
234 In Samba-3 on a domain controller (PDC or BDC), the domain name controls the domain
235 SID. On all prior versions the hostname (computer name, or netbios name) controlled
236 the SID. On a stand-alone server (SAS) the hostname still controls the SID.
240 <indexterm><primary>net</primary><secondary>getlocalsid</secondary></indexterm>
241 <indexterm><primary>net</primary><secondary>setlocalsid</secondary></indexterm>
242 The local machine SID can be backed up using this procedure (Samba-3):
244 &rootprompt; net getlocalsid > /etc/samba/my-local-SID
246 The contents of the file <filename>/etc/samba/my-local-SID</filename> will be:
248 SID for domain FRODO is: S-1-5-21-726309263-4128913605-1168186429
250 This SID can be restored by executing:
252 &rootprompt; net setlocalsid S-1-5-21-726309263-4128913605-1168186429
257 Samba 1.9.x stored the machine SID in the the file <filename>/etc/MACHINE.SID</filename>
258 from which it can be recovered and stored into the <filename>secrets.tdb</filename> file
259 using the procedure shown above.
263 Where the <filename>secrets.tdb</filename> file exists and a version of Samba 2.x or later
264 has been used there is no specific need to go through this update process. Samba-3 has the
265 ability to read the older tdb file and to perform an in-situ update to the latest tdb format.
266 This is not a reversible process &smbmdash; it is a one-way upgrade.
270 <indexterm><primary>smbpasswd</primary></indexterm>
271 In the course of the Samba 2.0.x series the <command>smbpasswd</command> was modified to
272 permit the domain SID to be captured to the <filename>secrets.tdb</filename> file by executing:
274 &rootprompt; smbpasswd -S PDC -Uadministrator%password
279 The release of the Samba 2.2.x series permitted the SID to be obtained by executing:
281 &rootprompt; smbpasswd -S PDC -Uadministrator%password
283 From which the SID could be copied to a file and then it could be written to the Samba 2.2.x
284 <filename>secrets.tdb</filename> file by executing:
286 &rootprompt; smbpasswd -W S-1-5-21-726309263-4128913605-1168186429
291 <indexterm><primary>rpcclient</primary></indexterm>
292 <indexterm><primary>net</primary><secondary>rpc</secondary><tertiary>info</tertiary></indexterm>
293 Domain security information, that includes the domain SID, can be obtained from Samba-2.2.x
294 systems by executing:
296 &rootprompt; rpcclient lsaquery -Uroot%password
298 This can also be done with Samba-3 by executing:
300 &rootprompt; net rpc info -Uroot%password
301 Domain Name: MIDEARTH
302 Domain SID: S-1-5-21-726309263-4128913605-1168186429
303 Sequence number: 1113415916
305 Num domain groups: 86
308 It is a very good practice to store this SID information in a safely kept file, just in
309 case it is ever needed at a later date.
313 <indexterm><primary>passdb backend</primary></indexterm>
314 <indexterm><primary>LDAP</primary></indexterm>
315 <indexterm><primary>SID</primary></indexterm>
316 Take note that the domain SID is used extensively in Samba. Where LDAP is used for the
317 <parameter>passdb backend</parameter>, all user, group, and trust accounts are encoded
318 with the domain SID. This means that if the domain SID changes for any reason the entire
319 Samba environment can become broken thus requiring extensive corrective action is the
320 original SID can not be restored. Fortunately, it can be recovered from a dump of the
321 LDAP database. A dump of the LDAP directory database can be obtained by executing:
323 &rootprompt; slapcat -v -l filename.ldif
328 <indexterm><primary>SID</primary></indexterm>
329 <indexterm><primary>profiles</primary></indexterm>
330 <indexterm><primary>RPM</primary></indexterm>
331 When the domain SID has changed roaming profiles will cease to be functional. The recovery
332 of roaming profiles will necessitate resetting of the domain portion of the user SID
333 that owns the profile. This is encoded in the <filename>NTUser.DAT</filename> and can be
334 updated using the Samba <command>profiles</command> utility. Please be aware that not all
335 Linux distributions of the Samba RPMs do include this essential utility. Please do not
336 complain to the Samba Team if this utility is missing, that is an issue that must be
337 addressed to the creator of the RPM package. The Samba Team do their best to make
338 available all the tools needed to manage a Samba based Windows networking environment.
344 <title>Change of hostname</title>
347 <indexterm><primary>netbios</primary><secondary>machine name</secondary></indexterm>
348 <indexterm><primary>netbios name</primary></indexterm>
349 Samba uses two (2) methods by which the primary NetBIOS machine name (also known as a computer
350 name or the hostname) may be determined: If the &smb.conf; file contains an entry
351 <parameter>netbios name</parameter> entry its value will be used directly. In the absence
352 of such and entry the UNIX system hostname will be used.
356 Many sites have become victims of lost Samba functionality because the UNIX system
357 hostname was changed for one reason or another. Such a change will cause a new machine
358 SID to be generated. If this happens on a domain controller it will also change the
359 domain SID. These SIDs can be updated (restored) using the procedure outlined above.
363 Do NOT change the hostname or the <parameter>netbios name</parameter>. If this
364 is changed be sure to reset the machine SID to the original setting, otherwise
365 there may be serious interoperability and/or operational problems.
371 <title>Change of workgroup (domain) name</title>
374 <indexterm><primary>workgroup</primary></indexterm>
375 The domain name of a Samba server is identical with the workgroup name and is
376 set in the &smb.conf; file using the <parameter>workgroup</parameter> parameter.
377 This has been consistent throughout the history of Samba and across all versions.
381 <indexterm><primary>SID</primary></indexterm>
382 Be aware that when the workgroup name is changed a new SID will be generated.
383 The old domain SID can be reset using the procedure outlined earlier in this chapter.
389 <title>Location of config files</title>
392 The Samba-Team has maintained a constant default location for all Samba control files
393 throughout the life of the project. People who have produced binary packages of Samba
394 have varied the location of the Samba control files. This has led to some confusion
395 for network administrators.
399 <indexterm><primary>directory</primary></indexterm>
400 The Samba 1.9.x &smb.conf; file may be found either in the <filename>/etc</filename>
401 directory or in <filename>/usr/local/samba/lib</filename>.
405 During the life of the Samba 2.x release the &smb.conf; file was relocated
406 on Linux systems to the <filename>/etc/samba</filename> directory where it
407 remains located also for Samba 3.0.x installations.
411 <indexterm><primary>secrets.tdb</primary></indexterm>
412 Samba 2.x introduced the <filename>secrets.tdb</filename> file that is also stored in the
413 <filename>/etc/samba</filename> directory, or in the <filename>/usr/local/samba/lib</filename>
414 directory sub-system.
418 <indexterm><primary>smbd</primary></indexterm>
419 The location at which <command>smbd</command> expects to find all configuration and control
420 files is determined at the time of compilation of Samba. For versions of Samba prior to
421 3.0 one way to find the expected location of these files is to execute:
423 &rootprompt; strings /usr/sbin/smbd | grep conf
424 &rootprompt; strings /usr/sbin/smbd | grep secret
425 &rootprompt; strings /usr/sbin/smbd | grep smbpasswd
427 Note: The <command>smbd</command> executable may be located in the path
428 <filename>/usr/local/samba/sbin</filename>.
432 <indexterm><primary>compile-time</primary></indexterm>
433 Samba-3 provides a neat new way to track the location of all control files as well as to
434 find the compile-time options used as the Samba package was built. Here is how the dark
435 secrets of the internals of the location of control files within Samba executables can
438 &rootprompt; smbd -b | less
441 Built on: Mon Apr 11 20:23:27 MDT 2005
443 Build host: Linux frodo 2.6...
444 SRCDIR: /usr/src/packages/BUILD/samba-3.0.15/source
445 BUILDDIR: /usr/src/packages/BUILD/samba-3.0.15/source
450 SWATDIR: /usr/share/samba/swat
451 CONFIGFILE: /etc/samba/smb.conf
452 LOGFILEBASE: /var/log/samba
453 LMHOSTSFILE: /etc/samba/lmhosts
454 LIBDIR: /usr/lib/samba
456 LOCKDIR: /var/lib/samba
457 PIDDIR: /var/run/samba
458 SMB_PASSWD_FILE: /etc/samba/smbpasswd
459 PRIVATE_DIR: /etc/samba
465 It is important that both the &smb.conf; file and the <filename>secrets.tdb</filename> should
466 be backed up before attempting any upgrade. The <filename>secrets.tdb</filename> file is version
467 encoded and therefore a newer version may not work with an older version of Samba. A backup
468 means that it is always possible to revert a failed or problematic upgrade.
478 <title>Upgrading from Samba 1.x and 2.x to Samba-3</title>
481 Sites that are being upgraded from Samba-2 (or earlier versions) to Samba-3
482 may experience little difficulty or may require a lot of effort, depending
483 on the complexity of the configuration. Samba-1.9.x upgrades to Samba-3 will
484 generally be simple and straight forward, although no upgrade should be
485 attempted without proper planning and preparation.
489 There are two basic modes of use of Samba versions prior to Samba-3. The first
490 does not use LDAP, the other does. Samba-1.9.x did not provide LDAP support.
491 Samba-2.x could be compiled with LDAP support.
495 <title>Samba 1.9.x and 2.x Versions Without LDAP</title>
498 Where it is necessary to upgrade an old Samba installation to Samba-3
499 the following procedure can be followed:
504 <indexterm><primary>winbindd</primary></indexterm>
505 <indexterm><primary>smbd</primary></indexterm>
506 <indexterm><primary>nmbd</primary></indexterm>
507 Stop Samba. This can be done using the appropriate system tool
508 that is particular for each operating system or by executing the
509 <command>kill</command> command on <command>smbd, nmbd</command>
510 and on <command>winbindd</command>.
514 Find the location of the Samba &smb.conf; file - back it up to a
519 Find the location of the <filename>smbpasswd</filename> file -
520 back it up to a safe location.
524 Find the location of the <filename>secrets.tdb</filename> file -
525 back it up to a safe location.
529 <indexterm><primary>lock directory</primary></indexterm>
530 <indexterm><primary>/usr/local/samba/var/locks</primary></indexterm>
531 <indexterm><primary>/var/cache/samba</primary></indexterm>
532 <indexterm><primary>/var/lib/samba</primary></indexterm>
533 Find the location of the lock directory. This is the directory
534 in which Samba stores all its tdb control files. The default
535 location used by the Samba Team is in
536 <filename>/usr/local/samba/var/locks</filename> directory,
537 but on Linux systems the old location was under the
538 <filename>/var/cache/samba</filename> directory, however the
539 Linux Standards Base specified location is now under the
540 <filename>/var/lib/samba</filename> directory. Copy all the
541 tdb files to a safe location.
545 <indexterm><primary>RPM</primary></indexterm>
546 It is now safe to ugrade the Samba installation. On Linux systems
547 it is not necessary to remove the Samba RPMs becasue a simple
548 upgrade installation will automatically remove the old files.
552 On systems that do not support a reliable package management system
553 it is advisable either to delete the Samba old installation , or to
554 move it out of the way by renaming the directories that contain the
559 When the Samba upgrade has been installed the first step that should
560 be completed is to identify the new target locations for the control
561 files. Follow the steps shown in <link linkend="sbeug1"/> to locate
562 the correct directories to which each control file must be moved.
566 Do not change the hostname.
570 Do not change the workgroup name.
574 <indexterm><primary>testparm</primary></indexterm>
575 Execute the <command>testparm</command> to validate the &smb.conf; file.
576 This process will flag any parameters that are no longer supported.
577 It will also flag configuration settings that may be in conflict.
581 One solution that may be used to clean up and to update the &smb.conf;
582 file involves renaming it to <filename>smb.conf.master</filename> and
583 then executing the following:
585 &rootprompt; cd /etc/samba
586 &rootprompt; testparm -s smb.conf.master > smb.conf
588 <indexterm><primary>stripped</primary></indexterm>
589 The resulting &smb.conf; file will be stripped of all comments
590 and will be stripped of all non-conforming configuration settings.
594 <indexterm><primary>winbindd</primary></indexterm>
595 It is now safe to start Samba using the appropriate system tool.
596 Alternately, it is possible to just execute <command>nmbd, smbd</command>
597 and <command>winbindd</command> for the command line while logged in
606 <title>Applicable to all Samba 2.x to Samba-3 Upgrades</title>
609 <indexterm><primary>PDC</primary></indexterm>
610 <indexterm><primary>domain controller</primary></indexterm>
611 <indexterm><primary>inter-domain</primary></indexterm>
612 Samba 2.x servers that were running as a domain controller (PDC)
613 require changes to the configuration of the scripting interface
614 tools that Samba uses to perform operating system updates for
615 users, groups and trust accounts (machines and inter-domain).
619 <indexterm><primary>parameters</primary></indexterm>
620 The following parameters are new to Samba-3 and should be correctly
621 configured. Please refer to Chapters 3-6 in this book for examples
622 of use of the new parameters shown here:
623 <indexterm><primary>add group script</primary></indexterm>
624 <indexterm><primary>add machine script</primary></indexterm>
625 <indexterm><primary>add user to group script</primary></indexterm>
626 <indexterm><primary>delete group script</primary></indexterm>
627 <indexterm><primary>delete user from group script</primary></indexterm>
628 <indexterm><primary>set primary group script</primary></indexterm>
629 <indexterm><primary>passdb backend</primary></indexterm>
634 <member><para>add group script</para></member>
635 <member><para>add machine script</para></member>
636 <member><para>add user to group script</para></member>
637 <member><para>delete group script</para></member>
638 <member><para>delete user from group script</para></member>
639 <member><para>passdb backend</para></member>
640 <member><para>set primary group script</para></member>
645 <indexterm><primary>add machine script</primary></indexterm>
646 <indexterm><primary>add user script</primary></indexterm>
647 The <parameter>add machine script</parameter> functionality was previously
648 hanlded by the <parameter>add user script</parameter>, which in Samba-3 is
649 used exclusively to add user accounts.
653 <indexterm><primary>passdb backend</primary></indexterm>
654 <indexterm><primary>smbpasswd</primary></indexterm>
655 <indexterm><primary>tdbsam</primary></indexterm>
656 <indexterm><primary>useradd</primary></indexterm>
657 <indexterm><primary>usermod</primary></indexterm>
658 <indexterm><primary>userdel</primary></indexterm>
659 <indexterm><primary>groupadd</primary></indexterm>
660 <indexterm><primary>groupmod</primary></indexterm>
661 <indexterm><primary>groupdel</primary></indexterm>
662 Where the <parameter>passdb backend</parameter> used is either <constant>smbpasswd</constant>
663 (the default), or the new <constant>tdbsam</constant>, the system interface scripts
664 are typically used. These involve use of operating system tools such as
665 <command>useradd, usermod, userdel, groupadd, groupmod, groupdel</command>, etc.
669 <indexterm><primary>passdb backend</primary></indexterm>
670 <indexterm><primary>LDAP</primary></indexterm>
671 <indexterm><primary>Idealx</primary></indexterm>
672 Where the <parameter>passdb backend</parameter> makes use of an LDAP directory
673 it will be necessary either to use the <constant>smbldap-tools</constant> provided
674 by Idealx, or else to use an alternate toolset either provided by another third
675 party, or else home crafted tools to manage the LDAP directory accounts.
681 <title>Samba-2.x with LDAP support</title>
684 Samba version 2.x could be compiled for use either with, or without, LDAP.
685 The LDAP control settings in the &smb.conf; file in this old version are
686 completely different (and less complete) than they are with Samba-3. This
687 means that after migrating the control files it will be necessary to reconfigure
688 the LDAP settings entirely.
692 Follow the procedure outlined in <link linkend="sbeug2"/> to affect a migration
693 of all files to the correct locations.
697 <indexterm><primary>schema</primary></indexterm>
698 <indexterm><primary>WHATSNEW.txt</primary></indexterm>
699 The Samba SAM schema required for Samba-3 is significantly different from that
700 used with Samba 2.x. This means that the LDAP directory will need to be updated
701 using the procedure outlined in the Samba WHATSNEW.txt file that accompanies
702 all releases of Samba-3. This information is repeated here directly from this
705 This is an extract from the Samba-3.0.x WHATSNEW.txt file:
706 ==========================================================
710 The following issues are known changes in behavior between Samba 2.2 and
711 Samba 3.0 that may affect certain installations of Samba.
713 1) When operating as a member of a Windows domain, Samba 2.2 would
714 map any users authenticated by the remote DC to the 'guest account'
715 if a uid could not be obtained via the getpwnam() call. Samba 3.0
716 rejects the connection as NT_STATUS_LOGON_FAILURE. There is no
717 current work around to re-establish the 2.2 behavior.
719 2) When adding machines to a Samba 2.2 controlled domain, the
720 'add user script' was used to create the UNIX identity of the
721 machine trust account. Samba 3.0 introduces a new 'add machine
722 script' that must be specified for this purpose. Samba 3.0 will
723 not fall back to using the 'add user script' in the absence of
724 an 'add machine script'
726 ######################################################################
727 Passdb Backends and Authentication
728 ##################################
730 There have been a few new changes that Samba administrators should be
731 aware of when moving to Samba 3.0.
733 1) encrypted passwords have been enabled by default in order to
734 inter-operate better with out-of-the-box Windows client
735 installations. This does mean that either (a) a samba account
736 must be created for each user, or (b) 'encrypt passwords = no'
737 must be explicitly defined in smb.conf.
739 2) Inclusion of new 'security = ads' option for integration
740 with an Active Directory domain using the native Windows
741 Kerberos 5 and LDAP protocols.
743 MIT kerberos 1.3.1 supports the ARCFOUR-HMAC-MD5 encryption
744 type which is neccessary for servers on which the
745 administrator password has not been changed, or kerberos-enabled
746 SMB connections to servers that require Kerberos SMB signing.
747 Besides this one difference, either MIT or Heimdal Kerberos
748 distributions are usable by Samba 3.0.
751 Samba 3.0 also includes the possibility of setting up chains
752 of authentication methods (auth methods) and account storage
753 backends (passdb backend). Please refer to the smb.conf(5)
754 man page for details. While both parameters assume sane default
755 values, it is likely that you will need to understand what the
756 values actually mean in order to ensure Samba operates correctly.
758 The recommended passdb backends at this time are
760 * smbpasswd - 2.2 compatible flat file format
761 * tdbsam - attribute rich database intended as an smbpasswd
762 replacement for stand alone servers
763 * ldapsam - attribute rich account storage and retrieval
764 backend utilizing an LDAP directory.
765 * ldapsam_compat - a 2.2 backward compatible LDAP account
768 Certain functions of the smbpasswd(8) tool have been split between the
769 new smbpasswd(8) utility, the net(8) tool, and the new pdbedit(8)
770 utility. See the respective man pages for details.
772 ######################################################################
776 This section outlines the new features affecting Samba / LDAP
782 A new object class (sambaSamAccount) has been introduced to replace
783 the old sambaAccount. This change aids us in the renaming of
784 attributes to prevent clashes with attributes from other vendors.
785 There is a conversion script (examples/LDAP/convertSambaAccount) to
786 modify and LDIF file to the new schema.
790 $ ldapsearch .... -b "ou=people,dc=..." > sambaAcct.ldif
791 $ convertSambaAccount --sid=<Domain SID> \
792 --input=sambaAcct.ldif --output=sambaSamAcct.ldif \
793 --changetype=[modify|add]
795 The <DOM SID> can be obtained by running 'net getlocalsid
796 <DOMAINNAME>' on the Samba PDC as root. The changetype determines
797 the format of the generated LDIF output--either create new entries
798 or modify existing entries.
800 The old sambaAccount schema may still be used by specifying the
801 "ldapsam_compat" passdb backend. However, the sambaAccount and
802 associated attributes have been moved to the historical section of
803 the schema file and must be uncommented before use if needed.
804 The 2.2 object class declaration for a sambaAccount has not changed
805 in the 3.0 samba.schema file.
807 Other new object classes and their uses include:
809 * sambaDomain - domain information used to allocate rids
810 for users and groups as necessary. The attributes are added
811 in 'ldap suffix' directory entry automatically if
812 an idmap uid/gid range has been set and the 'ldapsam'
813 passdb backend has been selected.
815 * sambaGroupMapping - an object representing the
816 relationship between a posixGroup and a Windows
817 group/SID. These entries are stored in the 'ldap
818 group suffix' and managed by the 'net groupmap' command.
820 * sambaUnixIdPool - created in the 'ldap idmap suffix' entry
821 automatically and contains the next available 'idmap uid' and
824 * sambaIdmapEntry - object storing a mapping between a
825 SID and a UNIX uid/gid. These objects are created by the
826 idmap_ldap module as needed.
828 * sambaSidEntry - object representing a SID alone, as a Structural
829 class on which to build the sambaIdmapEntry.
832 New Suffix for Searching
833 ------------------------
835 The following new smb.conf parameters have been added to aid in directing
836 certain LDAP queries when 'passdb backend = ldapsam://...' has been
839 * ldap suffix - used to search for user and computer accounts
840 * ldap user suffix - used to store user accounts
841 * ldap machine suffix - used to store machine trust accounts
842 * ldap group suffix - location of posixGroup/sambaGroupMapping entries
843 * ldap idmap suffix - location of sambaIdmapEntry objects
845 If an 'ldap suffix' is defined, it will be appended to all of the
846 remaining sub-suffix parameters. In this case, the order of the suffix
847 listings in smb.conf is important. Always place the 'ldap suffix' first
850 Due to a limitation in Samba's smb.conf parsing, you should not surround
851 the DN's with quotation marks.
860 <title>Updating a Samba-3 Installation</title>
863 The key concern in this section is to deal with the changes that have been
864 affected in Samba-3 between the samba-3.0.0 release and the current update.
865 Network administrators have expressed concerns over the steps that should be
866 taken to update Samba-3 versions.
870 <indexterm><primary>control files</primary></indexterm>
871 The information in <link linkend="sbeug1"/> would not be necessary if every
872 person who has ever produced Samba executable (binary) files could agree on
873 the preferred location of the &smb.conf; file and other Samba control files.
874 Clearly, such agreement is further away than a pipe-dream.
878 <indexterm><primary>vendors</primary></indexterm>
879 Vendors and packagers who produce Samba binary installable packages do not,
880 as a rule, use the default paths used by the Samba-Team for the location of
881 the binary files, the &smb.conf; file, and the Samba control files (tdb's
882 as well as files such as <filename>secrets.tdb</filename>. This means that
883 the network or UNIX administrator who sets out to build the Samba executable
884 files from the Samba tarball must take particular care. Failure to take care
885 will result in both the original vendors' version of Samba remaining installed
886 as well as the new version that will be installed in the default location used
887 by the Samba-Team. This can lead to confusion and to much lost time as the
888 uninformed administrator deals with apparent failure of the update to take
893 <indexterm><primary>packages</primary></indexterm>
894 The best advice for those lacking in code compilation experience is to use
895 only vendor (or Samba-Team) provided binary packages. The Samba packages
896 that are provided by the Samba-Team are generally built to use file paths
897 that are compatible with the original operating system vendors' practices.
901 <indexterm><primary>binary package</primary></indexterm>
902 <indexterm><primary>binary files</primary></indexterm>
903 If you are not sure whether or a binary package complies with the operating
904 system vendors' practices it is better to ask the package maintainer via
905 email to be certain than to waste much time dealing with the nuances.
906 Alternately, just diagnose the paths specified by the binary files following
907 the procedure outlined above.
911 <title>Samba-3 to Samba-3 updates on the Same Server</title>
914 The guidance in this section deals with updates to an existing
915 Samba-3 server installation.
919 <title>Updating from Samba Versions Earlier than 3.0.5</title>
922 With the provision that the binary Samba-3 package has been built
923 with the same path and feature settings as the existing Samba-3
924 package that is being updated, an update of Samab-3 versions 3.0.0
925 through 3.0.4 can be updated to 3.0.5 without loss of functionality
926 and without need to change either the &smb.conf; file or, where
927 used, the LDAP schema.
933 <title>Updating from Samba Versions between 3.0.6 and 3.0.10</title>
936 <indexterm><primary>schema</primary></indexterm>
937 <indexterm><primary>LDAP</primary><secondary>schema</secondary></indexterm>
938 When updating versions of Samba-3 prior to 3.0.6 to 3.0.6-3.0.10
939 it is necessary only to update the LDAP schema (where LDAP is used).
940 Always use the LDAP schema file that is shipped with the latest Samba-3
945 <indexterm><primary>ldapsam</primary></indexterm>
946 <indexterm><primary>tdbsam</primary></indexterm>
947 <indexterm><primary>passdb backend</primary></indexterm>
948 Samba-3.0.6 introduced the ability to remember the last 'n' number
949 of passwords a user has used. This information will work only with
950 the <constant>tdbsam</constant> and <constant>ldapsam</constant>
951 <parameter>passdb backend</parameter> facilities.
955 After updating the LDAP schema, do not forget to reindex the LDAP database.
961 <title>Updating from Samba Versions after 3.0.6 to a Current Release</title>
964 <indexterm><primary>winbindd</primary></indexterm>
965 Samba-3.0.8 introduced changes in how the <parameter>username map</parameter>
966 behaves. It also included a change in behavior of <command>winbindd</command>.
967 Please refer to the man page for &smb.conf; before implementing any update
968 from versions prior to 3.0.8 to a current version.
972 <indexterm><primary>privileges</primary></indexterm>
973 In Samba-3.0.11 a new privileges interface was implemented. Please
974 refer to <link linkend="ch6-ppc"/> for information regarding this new
975 feature. It is not necessary to implement the privileges interface, but it
976 is one that has been requested for several years and thus may be of interest
981 In Samba-3.0.11 there were some functional changes to the <parameter>ldap user suffix</parameter>
982 and to the <parameter>ldap machine suffix</parameter> behaviors. The following
983 information has been extracted from the WHATSNEW.txt file from this release:
989 If "ldap user suffix" or "ldap machine suffix" are defined in
990 smb.conf, all user-accounts must reside below the user suffix,
991 and all machine and inter-domain trust-accounts must be located
992 below the machine suffix. Previous Samba releases would fall
993 back to searching the 'ldap suffix' in some cases.
1001 <title>Migrating Samba-3 to a New Server</title>
1004 The two most likely candidates for replacement of a server are
1005 domain member servers and domain controllers. Each needs to be
1006 handled slightly differently.
1010 <title>Replacing a Domain Member Server</title>
1013 <indexterm><primary>DMS</primary></indexterm>
1014 Replacement of a domain member server (DMS) should be done
1015 using the same procedure as outlined in <link linkend="unixclients"/>.
1019 Usually the new server will be introduced with a temporary name. After
1020 the old server data has been migrated to the new server it is customary
1021 that the new server will be renamed to that of the old server. This will
1022 change its SID and will necessitate re-joining to the domain.
1026 <indexterm><primary>smbd</primary></indexterm>
1027 <indexterm><primary>nmbd</primary></indexterm>
1028 <indexterm><primary>winbindd</primary></indexterm>
1029 <indexterm><primary>wins.dat</primary></indexterm>
1030 <indexterm><primary>browse.dat</primary></indexterm>
1031 <indexterm><primary>resolution</primary></indexterm>
1032 Following a change of hostname (netbios name) it is a good idea on all servers to
1033 shutdown the Samba <command>smbd, nmbd</command> and <command>winbindd</command>
1034 services, delete the <filename>wins.dat</filename> and <filename>browse.dat</filename>
1035 files, then restart Samba. This will ensure that the old name and IP address
1036 information is no longer able to interfere with name to IP address resolution.
1037 If this is not done, there can be temporary name resolution problems. These
1038 problems usually clear within 45 minutes of a name change, but can persist for
1039 a longer period of time.
1043 <indexterm><primary>DMS</primary></indexterm>
1044 <indexterm><primary>/etc/passwd</primary></indexterm>
1045 <indexterm><primary>/etc/shadow</primary></indexterm>
1046 <indexterm><primary>/etc/group</primary></indexterm>
1047 If the old DMS had local accounts, it is necessary to create on the new DMS
1048 the same accounts with the same UID and GID for each account. Where the
1049 <parameter>passdb backend</parameter> database is stored in the <constant>smbpasswd</constant>
1050 or in the <constant>tdbsam</constant> format the user and group account
1051 information for UNIX accounts, that match the Samba accounts, will reside in
1052 the system <filename>/etc/passwd, /etc/shadow</filename> and
1053 <filename>/etc/group</filename> files. In this case be sure to copy these
1054 account entries to the new target server.
1058 <indexterm><primary>nss_ldap</primary></indexterm>
1059 Where the user accounts for both UNIX and Samba are stored in LDAP, the new
1060 target server must be configured to use the <command>nss_ldap</command> tool set.
1061 This will then automatically ensure that the appropriate user entities are
1062 available on the new server.
1068 <title>Replacing a Domain Controller</title>
1071 <indexterm><primary>domain</primary><secondary>controller</secondary></indexterm>
1072 In the past, people who replaced a Windows NT4 domain controller would typically
1073 install a new server, create printers and file shares on it, then migrate across
1074 all data that was destined to reside on it. The same can of course be done with
1079 From recent mailing list postings it would seem that some administrators
1080 have the intent to just replace the old Samba server with a new one with
1081 the same name as the old one. In this case, simply follow the same process
1082 as upgrading a Samba 2.x system in respect of the following:
1087 Where UNIX (POSIX) user and group accounts are stored in the system
1088 <filename>/etc/passwd, /etc/shadow</filename> and
1089 <filename>/etc/group</filename> files be sure to add the same accounts
1090 with identical UID and GID values for each user.
1094 Where LDAP is used, if the new system is intended to be the LDAP server
1095 migrate it across by configuring the LDAP server
1096 (<filename>/etc/openldap/slapd.conf</filename>). The directory can either
1097 be populated initially by setting this LDAP server up as a slave, or else
1098 by dumping the data from the old LDAP server using the <command>slapcat</command>
1099 command and then reloading the same data into the new LDAP server using the
1100 <command>slapadd</command> command. Do not forget to install and configure
1101 the <command>nss_ldap</command> tool and the <filename>/etc/nsswitch.conf</filename>
1102 (as shown in Chapter 5).
1106 Copy the &smb.conf; file from the old server to the new server into the correct
1107 location as indicated previously in this chapter.
1111 Copy the <filename>secrets.tdb</filename> file, the <filename>smbpasswd</filename>
1112 file (if it is used), the <filename>/etc/samba/passdb.tdb</filename> file (only
1113 used by the <constant>tdbsam</constant> backend), and all the tdb control files
1114 from the old system to the correct location on the new system.
1118 Before starting the Samba daemons, verify that the hostname of the new server
1119 is identical with that of the old one. Note: The IP address can be different
1120 from that of the old server.
1124 Copy all files from the old server to the new server, taking precaution to
1125 preserve all file ownership and permissions as well as any POSIX ACLs that
1126 may have been created on the old server.
1131 When replacing a Samba domain controller (PDC or BDC) that uses LDAP, the new server
1132 need simply be configured to use the LDAP directory, and for the rest it should just
1133 work. The domain SID is obtained from the LDAP directory as part of the first connect
1134 to the LDAP directory server.
1138 All Samba servers, other than one that uses LDAP, depend on the tdb files, and in
1139 particular the <filename>secrets.tdb</filename> file. So long as the tdb files are
1140 all in place, the &smb.conf; file is preserved, and either the hostname is identical
1141 or the <parameter>netbios name</parameter> is set to the original server name, Samba
1142 should correctly pick up the original SID, and preserve all other settings. It is
1143 sound advice to validate this before turning the system over to users.
1151 <title>Migration of Samba Accounts to Active Directory</title>
1154 Yes, it works. The Windows ADMT tool can be used to migrate Samba accounts
1155 to MS Active Directory. There are a few pitfalls to be aware of:
1160 Administrator password must be THE SAME on the Samba server,
1161 the 2003 ADS, and the local Administrator account on the workstations.
1162 Perhaps this goes without saying, but there needs to be an account
1163 called <constant>Administrator</constant> in your Samba domain, with
1164 full administrative (root) rights to that domain.
1168 In the Advanced/DNS section of the TCP/IP settings on your Windows
1169 workstations, make sure <parameter>DNS suffix for this
1170 connection</parameter> field is blank.
1174 Because you are migrating from Samba, user passwords cannot be
1175 migrated. You'll have to reset everyone's passwords. (If you were
1176 migrating from NT4 to ADS, you could migrate passwords as well.)
1180 To date this has not been attempted with roaming profile support;
1181 it has been documented as working with local profiles.
1185 Disable the Windows Firewall on all workstations. Otherwise,
1186 workstations won't be migrated to the new domain.
1190 <indexterm><primary>ADMT</primary></indexterm>
1191 When migrating machines, always test first (using ADMT's test mode)
1192 and satisfy all errors before committing the migration. Note that the
1193 test will always fail, because the machine will not have been actually
1194 migrated. You'll need to interpret the errors to know whether the
1195 failure was due to a problem, or simply due to the fact that it was just
1203 <indexterm><primary>ADMT</primary></indexterm>
1204 There are some significant benefits of using the ADMT, besides just
1205 migrating user accounts. ADMT can be found on the Windows 2003 CD.
1210 You can also migrate workstations remotely. You can specify that SIDs
1211 be simply added instead of replaced, giving you the option of joining a
1212 workstation back to the old domain if something goes awry. The
1213 workstations will be joined to the new domain.
1217 Not only are user accounts migrated from the old domain to the new
1218 domain, but ACLs on the workstations are migrated as well. Like SIDs,
1219 ACLs can be added instead of replaced.
1223 Locally stored user profiles on workstations are migrated as well,
1224 presenting almost no disruption to the user. Saved passwords will be
1225 lost, just as when you administratively reset the password in Windows ADS.
1229 The ADMT lets you test all operations before actually performing the
1230 migration. Accounts and workstations can be migrated individually or in
1231 batches. User accounts can be safely migrated all at once (since no
1232 changes are made on the original domain); It is recommended to migrate only one
1233 or two workstations as a test before committing them all.