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 It was a little difficult to select an appropriate title for this chapter.
8 From email messages on the Samba mailing lists it is clear that many people
9 consider the updating and upgrading of Samba to be a migration matter. Others
10 talk about migrating Samba servers when in fact the issue at hand is one of
11 installing a new Samba server to replace an older existing Samba server.
15 There has also been much talk about migration of Samba-3 from an smbpasswd
16 passdb backend to the use of the tdbsam or ldapsam facilities that are new
21 Clearly, there is not a great deal of clarity in the terminology that various
22 people apply to these modes by which Samba servers are updated. This is further
23 highlighted by an email posting that included the following neat remark:
27 I like the <quote>net rpc vampire</quote> on NT4, but that to my surprise does
28 not seem to work against a Samba PDC and, if addressed in the Samba to Samba
29 context in either book, I could not find it.
33 So in response to the significant request for these situations to be better
34 documented this chapter has now been added. Your contributions and documentation
35 of real-world experiences will be a most welcome addition to this chapter.
39 <title>Introduction</title>
42 A Windows network administrator explained in an email what changes he was
43 planning to make and and followed with the question: <quote>Anyone done this before?</quote>.
44 Many of us have upgraded and updated Samba without incident. Others have
45 experienced much pain and user frustration. So it is to be hoped that the
46 notes in this chapter will make a positive difference by assuring that
47 someone will be saved a lot of discomfort.
51 Before anyone commences an upgrade or an update of Samba the one cardinal
52 rule that must be observed is: Backup all Samba configuration files in
53 case it is necessary to revert to the old version. Even if you do not like
54 this precautionary step, users will punish an administrator who
55 fails to take adequate steps to avoid situations that may inflict lost
56 productivity on a user.
60 It is prudent also to backup all data files on the server before attempting
61 to perform a major upgrade. Many administrators have experienced the consequences
62 of failure to take adequate precautions. So what is adequate? That is simple!
63 If data is lost during an upgrade or and update and it can not be restored
64 the precautions take were inadequate. If a backup was not needed, but was available,
65 precaution was on the side of the victor.
69 <title>Cautions and Notes</title>
72 Someone once said, <quote>It is good to be sorry, but better never to need to be!</quote>
73 These are wise words of advice to those contemplating a Samba upgrade or update.
77 This is as good a time as any to define the terms <constant>upgrade</constant> and
78 <constant>update</constant>. The term <constant>upgrade</constant> is used to refer to
79 the installation of a version of Samba that is a whole generation or more ahead of
80 that which is installed. Generations are indicated by the first digit of the version
81 number. So far Samba has been release in generations 1.x, 2.x, 3.x and currently 4.0
86 The term <constant>update</constant> is used to refer to a minor version number installation
87 in place of one of the same generation. For example, updating from Samba 3.0.10 to 3.0.14
88 is an update. The move from Samba 2.0.7 to 3.0.14 is an upgrade.
92 While the use of these terms is an exercise in semantics, what needs to be realized
93 is that there are major functional differences between a Samba 2.x release and a Samba
94 3.0.x release. Such differences may require a significantly different approach to
95 solving the same networking challenge and generally requires careful review of the
96 latest documentation to identify precisely how the new installation may need to be
97 modified to preserve prior functionality.
101 There is an old axiom that says, <quote>The greater the volume of the documentation
102 the greater the risk that no-one will read it, but where there is no documentation
103 no-one can read it!</quote>. While true, some documentation is an evil necessity.
104 It is to be hoped that this update to the documentation will avoid both extremes.
108 <title>Security Identifiers (SIDs)</title>
111 Before the days of Windows NT and OS/2 every Windows and DOS networking client
112 that used the SMB protocols was an entirely autonomous entity. There was no concept
113 of a security identifier for a machine or a user outside of the username, the
114 machine name, and the workgroup name. In actual fact, these were not security identifies
115 in the same context as the way that the SID is used since the development of
120 Versions of Samba prior to 1.9 did not make use of a SID, instead they make exclusive use
121 of the username that is embedded in the SessionSetUpAndX component of the connection
122 setup process between a Windows client and an SMB/CIFS server.
126 Around November 1997 support was added to Samba-1.9 to handle the Windows security
127 rpc based protocols that implemented support for Samba to store a machine SID. This
128 information was stored in a file called <filename>MACHINE.SID.</filename>
132 Within the life time of the early Samba 2.x series the machine SID information was
133 relocated into a tdb file called <filename>secrets.tdb</filename>, which is where is
134 is still located in Samba 3.0.x along with other information that pertains to the
135 local machine and its role within a domain security context.
139 There are two types of SID, those pertaining to the machine itself and the domain to
140 which it may belong, and those pertaining to users and groups within the security
141 context of the local machine (in the case of stand-alone servers (SAS) and domain member
146 When the Samba <command>smbd</command> daemon is first started, if the <filename>secrets.tdb</filename>
147 file does not exist it is created at the first client connection attempt. If this file does
148 exist, <command>smbd</command> checks that there is a machine SID (if it is a domain controller
149 it searches for the domain SID). If <command>smbd</command> does not find one for the current
150 name of the machine or for the current name of the workgroup a new SID will be generated and
151 then written to the <filename>secrets.tdb</filename> file. The SID is generated in a non-determinative
152 manner. This means that each time it is generated for a particular combination of machine name
153 (hostname) and domain name (workgroup) it will be different.
157 The SID is the key used by MS Windows networking for all networking operations. This means
158 that when the machine or domain SID changes all security encoded objects such as profiles
159 and ACLs may become unusable.
163 It is of paramount importance that the machine and domain SID must be backed up so that in
164 the event of a change of hostname (machine name) or domain name (workgroup) the SID can
165 be restored to its previous value.
169 The local machine SID can be backed up using this procedure (Samba-3):
171 &rootprompt; net getlocalsid > /etc/samba/my-local-SID
173 The contents of the file <filename>/etc/samba/my-local-SID</filename> will be:
175 SID for domain FRODO is: S-1-5-21-726309263-4128913605-1168186429
177 This SID can be restored by executing:
179 &rootprompt; net setlocalsid S-1-5-21-726309263-4128913605-1168186429
184 Samba 1.9.x stored the machine SID in the the file <filename>/etc/MACHINE.SID</filename>
185 from which it can be recovered and stored into the <filename>secrets.tdb</filename> file
186 using the procedure shown above.
190 Where the <filename>secrets.tdb</filename> file exists and a version of Samba 2.x or later
191 has been used there is no specific need to go through this update process.
195 In the course of the Samba 2.0.x series the <command>smbpasswd</command> was modified to
196 permit the domain SID to be captured to the <filename>secrets.tdb</filename> file by executing:
198 &rootprompt; smbpasswd -S PDC -Uadministrator%password
203 The release of the Samba 2.2.x series permitted the SID to be obtained by executing:
205 &rootprompt; smbpasswd -S PDC -Uadministrator%password
207 From which the SID could be copied to a file and then it could be written to the
208 <filename>secrets.tdb</filename> file by executing:
210 &rootprompt; smbpasswd -W S-1-5-21-726309263-4128913605-1168186429
215 Domain security information, that includes the domain SID, can be obtained from Samba-2.2.x
216 systems by executing:
218 &rootprompt; rpcclient lsaquery -Uroot%password
220 This can also be done with Samba-3 by executing:
222 &rootprompt; net rpc info -Uroot%password
223 Domain Name: MIDEARTH
224 Domain SID: S-1-5-21-726309263-4128913605-1168186429
225 Sequence number: 1113415916
227 Num domain groups: 86
230 It is a very good practice to store this SID information in a safely kept file, just in
231 case it is ever needed at a later date.
235 Take note that the domain SID is used extensively in Samba. Where LDAP is used for the
236 <parameter>passdb backend</parameter>, all user, group, and trust accounts are encoded
237 with the domain SID. This means that if the domain SID changes for any reason the entire
238 Samba environment can become broken thus requiring extensive corrective action is the
239 original SID can not be restored. Fortunately, it can be recovered from a dump of the
240 LDAP database. A dump of the LDAP directory database can be obtained by executing:
242 &rootprompt; slapcat -v -l filename.ldif
247 When the domain SID has changed roaming profiles will cease to be functional. The recovery
248 of roaming profiles will necessitate resetting of the domain portion of the user SID
249 that owns the profile. This is encoded in the <filename>NTUser.DAT</filename> and can be
250 updated using the Samba <command>profiles</command> utility. Please be aware that not all
251 Linux distributions of the Samba RPMs do include this essential utility. Please do not
252 complain to the Samba Team if this utility is missing, that is an issue that must be
253 addressed to the creator of the RPM package. The Samba Team do their best to make
254 available all the tools needed to manage a Samba based Windows networking environment.
260 <title>Change of hostname</title>
263 Samba uses two (2) methods by which the primary NetBIOS machine name (also known as a computer
264 name or the hostname) may be determined: If the &smb.conf; file contains an entry
265 <parameter>netbios name</parameter> entry its value will be used directly. In the absence
266 of such and entry the UNIX system hostname will be used.
270 Many sites have become victims of lost Samba functionality because the UNIX system
271 hostname was changed for one reason or another. Such a change will cause a new machine
272 SID to be generated. If this happens on a domain controller it will also change the
273 domain SID. These SIDs can be updated (restored) using the procedure outlined above.
277 Do NOT change the hostname or the <parameter>netbios name</parameter>. If this
278 is changed be sure to reset the machine SID to the original setting, otherwise
279 there may be serious interoperability and/or operational problems.
285 <title>Change of workgroup (domain) name</title>
288 The domain name of a Samba server is identical with the workgroup name and is
289 set in the &smb.conf; file using the <parameter>workgroup</parameter> parameter.
290 This has been consistent throughout the history of Samba and across all versions.
294 Be aware that when the workgroup name is changed a new SID will be generated.
295 The old domain SID can be reset using the procedure outlined earlier in this chapter.
301 <title>Location of config files</title>
304 The Samba 1.9.x &smb.conf; file may be found either in the <filename>/etc</filename>
305 directory or in <filename>/usr/local/samba/lib</filename>.
309 During the life of the Samba 2.x release the &smb.conf; file was relocated
310 on Linux systems to the <filename>/etc/samba</filename> directory where it
311 remains located also for Samba 3.0.x installations.
315 Samba 2.x introduced the secrets.tdb file that is also stored in the
316 <filename>/etc/samba</filename> directory, or in the <filename>/usr/local/samba/lib</filename>
317 directory sub-system.
321 The location at which <command>smbd</command> expects to find all configuration and control
322 files is determined at the time of compilation of Samba. For versions of Samba prior to
323 3.0 one way to find the expected location of these files is to execute:
325 &rootprompt; strings /usr/sbin/smbd | grep conf
326 &rootprompt; strings /usr/sbin/smbd | grep secret
327 &rootprompt; strings /usr/sbin/smbd | grep smbpasswd
329 Note: The <command>smbd</command> executable may be located in the path
330 <filename>/usr/local/samba/sbin</filename>.
334 Samba-3 provides a neat new way to track the location of all control files as well as to
335 find the compile-time options used as the Samba package was built. Here is how the dark
336 secrets of the internals of Samba can be uncovered:
338 &rootprompt; smbd -b | less
341 Built on: Mon Apr 11 20:23:27 MDT 2005
343 Build host: Linux frodo 2.6...
344 SRCDIR: /usr/src/packages/BUILD/samba-3.0.15/source
345 BUILDDIR: /usr/src/packages/BUILD/samba-3.0.15/source
350 SWATDIR: /usr/share/samba/swat
351 CONFIGFILE: /etc/samba/smb.conf
352 LOGFILEBASE: /var/log/samba
353 LMHOSTSFILE: /etc/samba/lmhosts
354 LIBDIR: /usr/lib/samba
356 LOCKDIR: /var/lib/samba
357 PIDDIR: /var/run/samba
358 SMB_PASSWD_FILE: /etc/samba/smbpasswd
359 PRIVATE_DIR: /etc/samba
365 It is important that both the &smb.conf; file and the <filename>secrets.tdb</filename> should
366 be backed up before attempting any upgrade. The <filename>secrets.tdb</filename> file is version
367 encoded and therefore a newer version may not work with an older version of Samba. A backup
368 means that it is always possible to revert a failed or problematic upgrade.
378 <title>Upgrading from Samba 1.x and 2.x to Samba-3</title>
381 Sites that are being upgraded from Samba-2 (or earlier versions) to Samba-3
382 may experience little difficulty or may require a lot of effort, depending
383 on the complexity of the configuration. Samba-1.9.x upgrades to Samba-3 will
384 generally be simple and straight forward, although no upgrade should be
385 attempted without proper planning and preparation.
389 There are two basic modes of use of Samba versions prior to Samba-3. The first
390 does not use LDAP, the other does. Samba-1.9.x did not provide LDAP support.
391 Samba-2.x could be compiled with LDAP support.
395 <title>Samba 1.9.x and 2.x Versions Without LDAP</title>
398 Where it is necessary to upgrade an old Samba installation to Samba-3
399 the following procedure can be followed:
404 Stop Samba. This can be done using the appropriate system tool
405 that is particular for each operating system or by executing the
406 <command>kill</command> command on <command>smbd, nmbd</command>
407 and on <command>winbindd</command>.
411 Find the location of the Samba &smb.conf; file - back it up to a
416 Find the location of the
445 <title>Samba-2.x with LDAP support</title>
455 <title>Updating a Samba-3 Installation</title>
461 <title>Updating from Versions Earlier than 3.0.6</title>
469 <title>Updating from Versions between 3.0.7 and 3.0.10</title>
477 <title>Migrating Samba-3 to a New Server</title>