Another update. Fix bugs.

[Samba.git] / docs / Samba-Guide / SBE-UpgradingSamba.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
<chapter id="upgrades">
<title>Updating Samba-3</title>

<para>
It was a little difficult to select an appropriate title for this chapter.
From email messages on the Samba mailing lists it is clear that many people
consider the updating and upgrading of Samba to be a migration matter. Others
talk about migrating Samba servers when in fact the issue at hand is one of
installing a new Samba server to replace an older existing Samba server.
</para>

<para>
There has also been much talk about migration of Samba-3 from an smbpasswd
passdb backend to the use of the tdbsam or ldapsam facilities that are new
to Samba-3.
</para>

<para>
Clearly, there is not a great deal of clarity in the terminology that various
people apply to these modes by which Samba servers are updated. This is further 
highlighted by an email posting that included the following neat remark:
</para>

<blockquote><para>
I like the <quote>net rpc vampire</quote> on NT4, but that to my surprise does
not seem to work against a Samba PDC and, if addressed in the Samba to Samba
context in either book, I could not find it.
</para></blockquote>

<para>
So in response to the significant request for these situations to be better 
documented this chapter has now been added. Your contributions and documentation
of real-world experiences will be a most welcome addition to this chapter.
</para>

<sect1>
<title>Introduction</title>

<para>
A Windows network administrator explained in an email what changes he was
planning to make and and followed with the question: <quote>Anyone done this before?</quote>.
Many of us have upgraded and updated Samba without incident. Others have
experienced much pain and user frustration. So it is to be hoped that the
notes in this chapter will make a positive difference by assuring that
someone will be saved a lot of discomfort.
</para>

<para>
Before anyone commences an upgrade or an update of Samba the one cardinal
rule that must be observed is: Backup all Samba configuration files in
case it is necessary to revert to the old version. Even if you do not like
this precautionary step, users will punish an administrator who
fails to take adequate steps to avoid situations that may inflict lost
productivity on a user.
</para>

<warning><para>
Samba makes it possible to upgrade and update configuration files, but it
is not possible to downgrade the configuration files. Please ensure that
all configuration and control files are backed up to permit a down-grade
in the rare event that this may be necessary.
</para></warning>


<para>
It is prudent also to backup all data files on the server before attempting
to perform a major upgrade. Many administrators have experienced the consequences
of failure to take adequate precautions. So what is adequate? That is simple!
If data is lost during an upgrade or and update and it can not be restored
the precautions take were inadequate. If a backup was not needed, but was available,
precaution was on the side of the victor.
</para>

        <sect2>
        <title>Cautions and Notes</title>

        <para>
        Someone once said, <quote>It is good to be sorry, but better never to need to be!</quote>
        These are wise words of advice to those contemplating a Samba upgrade or update.
        </para>

        <para>
        This is as good a time as any to define the terms <constant>upgrade</constant> and
        <constant>update</constant>. The term <constant>upgrade</constant> is used to refer to
        the installation of a version of Samba that is a whole generation or more ahead of
        that which is installed. Generations are indicated by the first digit of the version
        number. So far Samba has been release in generations 1.x, 2.x, 3.x and currently 4.0
        is in development.
        </para>

        <para>
        The term <constant>update</constant> is used to refer to a minor version number installation
        in place of one of the same generation. For example, updating from Samba 3.0.10 to 3.0.14
        is an update. The move from Samba 2.0.7 to 3.0.14 is an upgrade.
        </para>

        <para>
        While the use of these terms is an exercise in semantics, what needs to be realized
        is that there are major functional differences between a Samba 2.x release and a Samba
        3.0.x release. Such differences may require a significantly different approach to
        solving the same networking challenge and generally requires careful review of the
        latest documentation to identify precisely how the new installation may need to be
        modified to preserve prior functionality.
        </para>

        <para>
        There is an old axiom that says, <quote>The greater the volume of the documentation
        the greater the risk that no-one will read it, but where there is no documentation
        no-one can read it!</quote>. While true, some documentation is an evil necessity.
        It is to be hoped that this update to the documentation will avoid both extremes.
        </para>

        <sect3>
        <title>Security Identifiers (SIDs)</title>

        <para>
        Before the days of Windows NT and OS/2 every Windows and DOS networking client
        that used the SMB protocols was an entirely autonomous entity. There was no concept
        of a security identifier for a machine or a user outside of the username, the
        machine name, and the workgroup name. In actual fact, these were not security identifies
        in the same context as the way that the SID is used since the development of
        Windows NT 3.10.
        </para>

        <para>
        Versions of Samba prior to 1.9 did not make use of a SID, instead they make exclusive use
        of the username that is embedded in the SessionSetUpAndX component of the connection
        setup process between a Windows client and an SMB/CIFS server. 
        </para>

        <para>
        Around November 1997 support was added to Samba-1.9 to handle the Windows security
        rpc based protocols that implemented support for Samba to store a machine SID. This
        information was stored in a file called <filename>MACHINE.SID.</filename>
        </para>

        <para>
        Within the life time of the early Samba 2.x series the machine SID information was
        relocated into a tdb file called <filename>secrets.tdb</filename>, which is where is
        is still located in Samba 3.0.x along with other information that pertains to the
        local machine and its role within a domain security context.
        </para>

        <para>
        There are two types of SID, those pertaining to the machine itself and the domain to
        which it may belong, and those pertaining to users and groups within the security
        context of the local machine (in the case of stand-alone servers (SAS) and domain member
        servers (DMS).
        </para>

        <para>
        When the Samba <command>smbd</command> daemon is first started, if the <filename>secrets.tdb</filename>
        file does not exist it is created at the first client connection attempt. If this file does
        exist, <command>smbd</command> checks that there is a machine SID (if it is a domain controller
        it searches for the domain SID). If <command>smbd</command> does not find one for the current
        name of the machine or for the current name of the workgroup a new SID will be generated and
        then written to the <filename>secrets.tdb</filename> file. The SID is generated in a non-determinative
        manner. This means that each time it is generated for a particular combination of machine name
        (hostname) and domain name (workgroup) it will be different.
        </para>

        <para>
        The SID is the key used by MS Windows networking for all networking operations. This means
        that when the machine or domain SID changes all security encoded objects such as profiles
        and ACLs may become unusable.
        </para>

        <note><para>
        It is of paramount importance that the machine and domain SID must be backed up so that in
        the event of a change of hostname (machine name) or domain name (workgroup) the SID can
        be restored to its previous value.
        </para></note>

        <para>
        The local machine SID can be backed up using this procedure (Samba-3):
<screen>
&rootprompt; net getlocalsid > /etc/samba/my-local-SID
</screen>
        The contents of the file <filename>/etc/samba/my-local-SID</filename> will be:
<screen>
SID for domain FRODO is: S-1-5-21-726309263-4128913605-1168186429
</screen>
        This SID can be restored by executing:
<screen>
&rootprompt; net setlocalsid S-1-5-21-726309263-4128913605-1168186429
</screen>
        </para>

        <para>
        Samba 1.9.x stored the machine SID in the the file <filename>/etc/MACHINE.SID</filename>
        from which it can be recovered and stored into the <filename>secrets.tdb</filename> file
        using the procedure shown above.
        </para>

        <para>
        Where the <filename>secrets.tdb</filename> file exists and a version of Samba 2.x or later
        has been used there is no specific need to go through this update process.
        </para>

        <para>
        In the course of the Samba 2.0.x series the <command>smbpasswd</command> was modified to
        permit the domain SID to be captured to the <filename>secrets.tdb</filename> file by executing:
<screen>
&rootprompt; smbpasswd -S PDC -Uadministrator%password
</screen>
        </para>

        <para>
        The release of the Samba 2.2.x series permitted the SID to be obtained by executing:
<screen>
&rootprompt; smbpasswd -S PDC -Uadministrator%password
</screen>
        From which the SID could be copied to a file and then it could be written to the
        <filename>secrets.tdb</filename> file by executing:
<screen>
&rootprompt; smbpasswd -W S-1-5-21-726309263-4128913605-1168186429
</screen>
        </para>

        <para>
        Domain security information, that includes the domain SID, can be obtained from Samba-2.2.x
        systems by executing:
<screen>
&rootprompt; rpcclient lsaquery -Uroot%password
</screen>
        This can also be done with Samba-3 by executing:
<screen>
&rootprompt; net rpc info -Uroot%password
Domain Name: MIDEARTH
Domain SID: S-1-5-21-726309263-4128913605-1168186429
Sequence number: 1113415916
Num users: 4237
Num domain groups: 86
Num local groups: 0
</screen>
        It is a very good practice to store this SID information in a safely kept file, just in
        case it is ever needed at a later date.
        </para>

        <para>
        Take note that the domain SID is used extensively in Samba. Where LDAP is used for the
        <parameter>passdb backend</parameter>, all user, group, and trust accounts are encoded
        with the domain SID. This means that if the domain SID changes for any reason the entire
        Samba environment can become broken thus requiring extensive corrective action is the 
        original SID can not be restored. Fortunately, it can be recovered from a dump of the
        LDAP database. A dump of the LDAP directory database can be obtained by executing:
<screen>
&rootprompt; slapcat -v -l filename.ldif
</screen>
        </para>

        <para>
        When the domain SID has changed roaming profiles will cease to be functional. The recovery
        of roaming profiles will necessitate resetting of the domain portion of the user SID
        that owns the profile. This is encoded in the <filename>NTUser.DAT</filename> and can be
        updated using the Samba <command>profiles</command> utility. Please be aware that not all
        Linux distributions of the Samba RPMs do include this essential utility. Please do not
        complain to the Samba Team if this utility is missing, that is an issue that must be
        addressed to the creator of the RPM package. The Samba Team do their best to make
        available all the tools needed to manage a Samba based Windows networking environment.
        </para>

        </sect3>

        <sect3>
        <title>Change of hostname</title>

        <para>
        Samba uses two (2) methods by which the primary NetBIOS machine name (also known as a computer
        name or the hostname) may be determined: If the &smb.conf; file contains an entry
        <parameter>netbios name</parameter> entry its value will be used directly. In the absence
        of such and entry the UNIX system hostname will be used.
        </para>

        <para>
        Many sites have become victims of lost Samba functionality because the UNIX system
        hostname was changed for one reason or another. Such a change will cause a new machine
        SID to be generated. If this happens on a domain controller it will also change the
        domain SID. These SIDs can be updated (restored) using the procedure outlined above.
        </para>

        <note><para>
        Do NOT change the hostname or the <parameter>netbios name</parameter>. If this
        is changed be sure to reset the machine SID to the original setting, otherwise
        there may be serious interoperability and/or operational problems.
        </para></note>

        </sect3>

        <sect3>
        <title>Change of workgroup (domain) name</title>

        <para>
        The domain name of a Samba server is identical with the workgroup name and is
        set in the &smb.conf; file using the <parameter>workgroup</parameter> parameter.
        This has been consistent throughout the history of Samba and across all versions.
        </para>

        <para>
        Be aware that when the workgroup name is changed a new SID will be generated.
        The old domain SID can be reset using the procedure outlined earlier in this chapter.
        </para>

        </sect3>

        <sect3 id="sbeug1">
        <title>Location of config files</title>

        <para>
        The Samba 1.9.x &smb.conf; file may be found either in the <filename>/etc</filename>
        directory or in <filename>/usr/local/samba/lib</filename>.
        </para>

        <para>
        During the life of the Samba 2.x release the &smb.conf; file was relocated
        on Linux systems to the <filename>/etc/samba</filename> directory where it
        remains located also for Samba 3.0.x installations.
        </para>

        <para>
        Samba 2.x introduced the secrets.tdb file that is also stored in the
        <filename>/etc/samba</filename> directory, or in the <filename>/usr/local/samba/lib</filename>
        directory sub-system.
        </para>

        <para>
        The location at which <command>smbd</command> expects to find all configuration and control
        files is determined at the time of compilation of Samba. For versions of Samba prior to
        3.0 one way to find the expected location of these files is to execute:
<screen>
&rootprompt; strings /usr/sbin/smbd | grep conf
&rootprompt; strings /usr/sbin/smbd | grep secret
&rootprompt; strings /usr/sbin/smbd | grep smbpasswd
</screen>
        Note: The <command>smbd</command> executable may be located in the path
        <filename>/usr/local/samba/sbin</filename>.
        </para>

        <para>
        Samba-3 provides a neat new way to track the location of all control files as well as to
        find the compile-time options used as the Samba package was built. Here  is how the dark
        secrets of the internals of Samba can be uncovered:
<screen>
&rootprompt; smbd -b | less
Build environment:
   Built by:    root@frodo
   Built on:    Mon Apr 11 20:23:27 MDT 2005
   Built using: gcc
   Build host:  Linux frodo 2.6...
   SRCDIR:      /usr/src/packages/BUILD/samba-3.0.15/source
   BUILDDIR:    /usr/src/packages/BUILD/samba-3.0.15/source

Paths:
   SBINDIR: /usr/sbin
   BINDIR: /usr/bin
   SWATDIR: /usr/share/samba/swat
   CONFIGFILE: /etc/samba/smb.conf
   LOGFILEBASE: /var/log/samba
   LMHOSTSFILE: /etc/samba/lmhosts
   LIBDIR: /usr/lib/samba
   SHLIBEXT: so
   LOCKDIR: /var/lib/samba
   PIDDIR: /var/run/samba
   SMB_PASSWD_FILE: /etc/samba/smbpasswd
   PRIVATE_DIR: /etc/samba
 ... 
</screen>
        </para>

        <para>
        It is important that both the &smb.conf; file and the <filename>secrets.tdb</filename> should
        be backed up before attempting any upgrade. The <filename>secrets.tdb</filename> file is version
        encoded and therefore a newer version may not work with an older version of Samba. A backup
        means that it is always possible to revert a failed or problematic upgrade.
        </para>

        </sect3>

        </sect2>

</sect1>

<sect1>
<title>Upgrading from Samba 1.x and 2.x to Samba-3</title>

<para>
Sites that are being upgraded from Samba-2 (or earlier versions) to Samba-3
may experience little difficulty or may require a lot of effort, depending
on the complexity of the configuration. Samba-1.9.x upgrades to Samba-3 will
generally be simple and straight forward, although no upgrade should be
attempted without proper planning and preparation.
</para>

<para>
There are two basic modes of use of Samba versions prior to Samba-3. The first
does not use LDAP, the other does. Samba-1.9.x did not provide LDAP support.
Samba-2.x could be compiled with LDAP support.
</para>

        <sect2>
        <title>Samba 1.9.x and 2.x Versions Without LDAP</title>

        <para>
        Where it is necessary to upgrade an old Samba installation to Samba-3
        the following procedure can be followed:
        </para>

        <procedure id="sbeug2">
                <step><para>
                Stop Samba. This can be done using the appropriate system tool
                that is particular for each operating system or by executing the
                <command>kill</command> command on <command>smbd, nmbd</command>
                and on <command>winbindd</command>.
                </para></step>

                <step><para>
                Find the location of the Samba &smb.conf; file - back it up to a
                safe location.
                </para></step>

                <step><para>
                Find the location of the <filename>smbpasswd</filename> file -
                back it up to a safe location.
                </para></step>

                <step><para>
                Find the location of the <filename>secrets.tdb</filename> file -
                back it up to a safe location.
                </para></step>

                <step><para>
                Find the location of the lock directory. This is the directory
                in which Samba stores all its tdb control files. The default
                location used by the Samba Team is in
                <filename>/usr/local/samba/var/locks</filename> directory,
                but on Linux systems the old location was under the
                <filename>/var/cache/samba</filename> directory, however the
                Linux Standards Base specified location is now under the
                <filename>/var/lib/samba</filename> directory. Copy all the
                tdb files to a safe location.
                </para></step>

                <step><para>
                It is now safe to ugrade the Samba installation. On Linux systems
                it is not necessary to remove the Samba RPMs becasue a simple
                upgrade installation will automatically remove the old files.
                </para>

                <para>
                On systems that do not support a reliable package management system
                it is advisable either to delete the Samba old installation , or to
                move it out of the way by renaming the directories that contain the
                Samab binary files.
                </para></step>

                <step><para>
                When the Samba upgrade has been installed the first step that should
                be completed is to identify the new target locations for the control
                files. Follow the steps shown in <link linend="sbeug1"/> to locate
                the correct directories to which each control file must be moved.
                </para></step>

                <step><para>
                Do not change the hostname.
                </para></step>

                <step><para>
                Do not change the workgroup name.
                </para></step>

                <step><para>
                Execute the <command>testparm</command> to validate the smb.conf file.
                This process will flag any parameters that are no longer supported.
                It will also flag configuration settings that may be in conflict.
                </para>

                <para>
                One solution that may be used to clean up and to update the &smb.conf;
                file involves renaming it to <filename>smb.conf.master</filename> and 
                then executing the following:
<screen>
&rootprompt; cd /etc/samba
&rootprompt; testparm -s smb.conf.master &gt; smb.conf
</screen>
                The resulting &smb.conf; file will be stripped of all comments
                and will be stripped of all non-conforming configuration settings.
                </para></step>

                <step><para>
                It is now safe to start Samba using the appropriate system tool.
                Alternately, it is possible to just execute <command>nmbd, smbd</command>
                and <command>winbindd</command> for the command line while logged in
                as the 'root' user.
                </para></step>

        </procedure>

        </sect2>

        <sect2>
        <title>Samba-2.x with LDAP support</title>

        <para>
        Samba version 2.x could be compiled for use either with, or without, LDAP.
        The LDAP control settings in the &smb.conf; file in this old version are
        completely different (and less complete) than they are with Samba-3. This
        means that after migrating the control files it will be necessary to reconfigure
        the LDAP settings entirely.
        </para>

        <para>
        Follow the procedure outlined in <link linkend="sbeug2"/> to affect a migration
        of all files to the correct locations.
        </para>

        <para>
        The Samba SAM schema required for Samba-3 is significantly different from that
        used with Samba 2.x. This means that the LDAP directory will need to be updated
        using the procedure outlined in the Samba WHATSNEW.txt file that accompanies
        all releases of Samba-3. This information is repeated here directly from this
        file:
<screen>
######################################################################
LDAP
####

This section outlines the new features affecting Samba / LDAP
integration.

New Schema
----------

A new object class (sambaSamAccount) has been introduced to replace
the old sambaAccount.  This change aids us in the renaming of
attributes to prevent clashes with attributes from other vendors.
There is a conversion script (examples/LDAP/convertSambaAccount) to
modify and LDIF file to the new schema.

Example:

  $ ldapsearch .... -b "ou=people,dc=..." &gt; sambaAcct.ldif
  $ convertSambaAccount --sid=&lt;Domain SID&gt; \
    --input=sambaAcct.ldif --output=sambaSamAcct.ldif \
    --changetype=[modify|add]

The &lt;DOM SID&gt; can be obtained by running 'net getlocalsid
&lt;DOMAINNAME&gt;' on the Samba PDC as root.  The changetype determines
the format of the generated LDIF output--either create new entries
or modify existing entries.

The old sambaAccount schema may still be used by specifying the
"ldapsam_compat" passdb backend.  However, the sambaAccount and
associated attributes have been moved to the historical section of
the schema file and must be uncommented before use if needed.
The 2.2 object class declaration for a sambaAccount has not changed
in the 3.0 samba.schema file.

Other new object classes and their uses include:

  * sambaDomain - domain information used to allocate rids
    for users and groups as necessary.  The attributes are added
    in 'ldap suffix' directory entry automatically if
    an idmap uid/gid range has been set and the 'ldapsam'
    passdb backend has been selected.

  * sambaGroupMapping - an object representing the
    relationship between a posixGroup and a Windows
    group/SID.  These entries are stored in the 'ldap
    group suffix' and managed by the 'net groupmap' command.

  * sambaUnixIdPool - created in the 'ldap idmap suffix' entry
    automatically and contains the next available 'idmap uid' and
    'idmap gid'

  * sambaIdmapEntry - object storing a mapping between a
    SID and a UNIX uid/gid.  These objects are created by the
    idmap_ldap module as needed.

  * sambaSidEntry - object representing a SID alone, as a Structural
    class on which to build the sambaIdmapEntry.


New Suffix for Searching
------------------------

The following new smb.conf parameters have been added to aid in directing
certain LDAP queries when 'passdb backend = ldapsam://...' has been
specified.

  * ldap suffix         - used to search for user and computer accounts
  * ldap user suffix    - used to store user accounts
  * ldap machine suffix - used to store machine trust accounts
  * ldap group suffix   - location of posixGroup/sambaGroupMapping entries
  * ldap idmap suffix   - location of sambaIdmapEntry objects

If an 'ldap suffix' is defined, it will be appended to all of the
remaining sub-suffix parameters.  In this case, the order of the suffix
listings in smb.conf is important.  Always place the 'ldap suffix' first
in the list.

Due to a limitation in Samba's smb.conf parsing, you should not surround
the DN's with quotation marks.
</screen>
        </para>

        </sect2>

</sect1>

<sect1>
<title>Updating a Samba-3 Installation</title>

<para>
</para>

        <sect2>
        <title>Updating from Versions Earlier than 3.0.6</title>

        <para>
        </para>

        </sect2>

        <sect2>
        <title>Updating from Versions between 3.0.7 and 3.0.10</title>

        <para>
        </para>

        </sect2>

        <sect2>
        <title>Migrating Samba-3 to a New Server</title>

        <para>
        </para>

        </sect2>

</sect1>

</chapter>