Migrating a Samba NT4 Domain to Samba AD (Classic Upgrade)

From SambaWiki
Revision as of 05:45, 18 April 2013 by Go8ose (talk | contribs) (→‎Notes about migrating from LDAP backend: add various notes from my experiences with classicupgrade)

PRENOTE This guide is only for replacing the "Provision Samba4" step on the main Samba4/Samba AD DC HOWTO wiki page. Please follow that page in full detail before attempting anything on this page.

Many people find themselves in a situation where they have an existing Samba3 based domain, complete with an extensive set of domain users and machines. The domain is functioning rather well, but they find themselves running into more and more dead ends -- things that Samba3 (especially if it is an older version) just doesn't support. The thought of moving their entire domain over to a new Windows AD server, or even a new Samba4 domain, with the requirement to completely rebuild their domain from the ground up is, to put it politely, rather unpleasant. However, there is a path to migrating an existing Samba3 domain, with all its members, to a new Samba4 domain, creating minimal disruption for users.

The following is a HOWTO for the Samba3 to Samba4 upgrade process.

Samba Tool

The Samba Tool (see: Samba-tool-external) is a collection of tools and scripts used to build, manage and debug a Samba4 instance.

The classicupgrade is a function built into the samba-tool (domain subsection). The intent of this function is to do a full replacement of an existing Samba3 supported domain. It is possible (at least in theory) to do the conversion of an existing Samba3 domain, shut down the old service and start the new Samba4 service, and the Windows users and member computers will simply re-connect to the new server without needing to manually re-join. Existing user domain profiles on member computers will appear exactly as they did on the old domain.

PLEASE NOTE: Make sure you thoroughly test your conversion and how your clients react before you activate your new server in your production environment! Once a Windows client finds and connects to the new server, it is not possible to go back!

Also, it is necessary to do testing on a separate network so that the old and new domain controllers don't clash. The issues with having both domains 'live' at the same time are:

  • The databases are not syncronised after the initial migration
  • Even if no changes are made to the DB, clients which see an AD DC will no longer honour NT4 system policies
  • The new Samba4 PDC and the old DC will both claim to hold the #1b name as the netbios domain master

The paths to certain files and directories for your Samba3 installation are often distribution specific (for example, /var/lib/samba vs. /etc/samba). Please be sure to verify and if necessary, modify paths used in examples appropriately.

Notes about migrating from LDAP backend

Make sure you have the ldap headers (apt-get install libldap2-dev for debian based distros)

To ease the migration pain, the migration will run as if 'ldapsam:trusted = yes' was in the [global] section of your Samba3 config file. This avoids the need to set up nsswitch.conf for LDAP migrations.

The following will check for duplicate SID's using slapcat, you will want to fix these manually before running the classicupgrade command, otherwise the import will give you the following error.

ERROR(<class 'samba.provision.ProvisioningError'>): uncaught exception - ProvisioningError: Please remove duplicate user sid entries before upgrade.

# A quick and dirty python script that checks for duplicat SID's using slapcat.
import os
data = os.popen("slapcat | grep sambaSID", 'r')
line = []
def anydup(thelist):
        dups = list(set([x for x in thelist if thelist.count(x) > 1]))
        for i in dups:
                print "Duplicate id: ", i
for each_line in data:

While you are checking for duplicate SID's, you may also want to make sure you don't have a username that is the same as a group name, otherwise you will get the following error.

ERROR(<class 'samba.provision.ProvisioningError'>): uncaught exception - ProvisioningError: Please remove common user/group names before upgrade.

You may wish to move your LDAP directory to the new server (though this isn't strictly necessary, as long as you account for this in your infrastructure and appropriately plan how to retire the old LDAP service once you are running a samba4 LDAP service). To move your ldap directory over to the new server, first on your Samba3 machine you will want to

 # slapcat > backup.ldif 

Then on your Samba4 machine install ldap and stop slapd (/etc/init.d/slapd stop typically) and perform the following commands

 # scp root@ip.to.samba3.machine:/path/to/backup.ldif /root
 # scp -r root@ip.to.samba3.machine:/etc/ldap /root
 # cd /etc && mv ldap ldap.orig && mv /root/ldap ./
 # slapadd -l /root/backup.ldif

Then restart the slapd. (It will likely not start right off the bat, chown openldap:openldap /var/lib/ldap -R and chown openldap:openldap /etc/ldap -R should take care of this, remember this IS distro specific, your paths and openldap user may be different! Also, it is probably very insecure to change ALL the files in those directories to the openldap user/group, but we will only use slapd breifly to do the import, then we can get rid of it completely.)

[NOTE: The samba-tool needs to include the ldap2 libraries. If you didn't have the libldap2-dev when you set up your Samba4 build through ./configure or ./configure.developer, you WILL need to redo those steps and redo the make and make install as well before you migrate or you will get errors about ldapsam.]

Be aware that various issues can come up when using the LDAP directory during the conversion. In particular:

  • If you have the sizelimit unset (it defaults to 500 in slapd 2.4) and you have more than that many user accounts you'll have problems
  • If the user that smb.conf is configured to use doesn't have appropriate ACLs you could have issues (though if you've already got samba in operation is very unlikely this will be an issue)
  • you may discover various problems with your LDAP objects that the classicupgrade script objects to (such as machine accounts not having all unix attributes, and a large variety of other problems). This is more likely to affect users who have a long history of coupling samba and LDAP together
  • Watch out for https://bugzilla.samba.org/show_bug.cgi?id=9797 (hopefully this will get fixed with samba 4.0.6)


The classicupgrade tool is designed to do in in-place migration of your domain. This is because it needs access to your Samba3 user database and configuration. There are times, however, when it may be better to do the migration on a new server (for example, if you are moving to new hardware platform to do your domain controller, or when you are doing independent testing to validate your process before actually migrating the production domain support). In this case, moving to a new server is just a matter of providing the critical information from the old server to the new host -- ie., by copying your domain information from the existing Samba3 domain to a new server.

In any event, please be sure you do thorough testing of your domain migration in a test environment before doing an in-place migration, since there is no way to back out once domain clients have connected to the new server.

First: Download, build and install the Samba4 binaries, either from one of the Alpha releases or from "git". On the Samba4/HOWTO page, follow the first three steps, stopping before the provision step.

Upgrading on a New Server

In order to have your existing Samba3 user database available to the conversion script, copy your Samba3 database directory (the location of all your Samba3 tdb files -- for example: /var/lib/samba) to the new server. eg.:

 # scp -r /var/lib/samba newserver:/path/to/samba3/tdbfiles

If your config file is not in the same directory as the tdb files, then copy it too. eg.:

 #scp /etc/samba/smb.conf newserver:/path/to/samba3tdb/

It may be less confusing if Samba3 is not installed on the new server, only the db and config files copied over. The LDAP headers and libraries do need to be installed if you are coming from that back end.

If you wish to change the host name of the new server, you can change the netbios name in the Samba3 conf file.

[NOTE: if you run the migration more than once, for example, in a testing environment, then make sure you remove the generated conf file in /usr/local/samba/etc directory. If the migration tool finds an existing smb.conf file, it will make use of the parameters there in subsequent conversion runs.]

Once you have copied over the database to the new server, the process is essentially the same as doing a migration "in place".

Upgrading In Place

It is also possible to perform the migration by building and installing Samba4 binaries on a currently existing Samba3 server. This will replace the currently running system with a Samba4 instance, populated with the users, groups and machine accounts from the previous Samba3 service.

Only do this after you have successfully tested your upgrade on another machine. One useful tip is to create an isolated network (possibly virtualized) with a copy of your existing Samba, a new test server and a clone of at least one Windows client. This way, you can run the conversion and see if the Windows client interacts correctly with the new domain.

  • First: stop all existing Samba3 services (smbd, nmbd, winbindd) but leave slapd running if you are moving from ldap backend.
  • Second: preform the upgrade by running the following (as "root"):
 # /usr/local/samba/bin/samba-tool domain classicupgrade --dbdir=/path/to/samba3/tdbfiles  --use-xattrs=yes  --realm=myname.org /path/to/samba3.conf


  • dbdir: path to the directory containing the tdb database files.
  • use-xattrs: use the underlying file system support for extended attributes. This assumes that your host OS supports this.
  • realm: You can specify the realm on the command line if it is not already specified in the Samba3 smb.conf file.

You can change the samba loglevel in the samba3.conf to see extra output if you are having problems. Be aware that this may cause MASSIVE amounts of output.

The migration process will

  • replicate user records (passwords, SID, etc.) into the new database
  • replicate existing machine accounts so that machines joined to the Samba3 domain will already be in the Samba4 domain
  • construct the basic DNS records necessary to support the domain. See below for instructions on how to add static IP records to the new DNS zone.

Once you have built the new domain, if you have not already done so in the previous steps, you must be sure to SHUT DOWN the original Samba3 server, as well as your original DNS service. Before you can log into any machine with a domain account, or join a new machine to the domain, you must be pointing to the new DNS server. Typically, this is done by changing your DHCP server to list the new Samba4 server as the DNS server.

  • Third: Stop slapd and start samba4 (follow from step 5 on using the Samba4/HOWTO page)
  • Fourth: VERY IMPORTANT Make sure the old Samba3, LDAP and DNS services DO NOT autostart on next boot. Look around the internet to find out how to stop them from starting, this is distro specific.
  • Also, this is a good point to make sure that both the Samba4 service and the new DNS service DO start on boot.

Migrating Groups

At this point, there are some issues with the classicupgrade tool migrating groups and their members from the previous Samba3 instance if the domain is using the tdb backend. In particular, if you try to do the migration on a new server by copying over the password and group files from /etc, the tool may not be able to iterate the groups. However, it is not at all difficult to create a script to add these groups manually from the source /etc/group file.

Assuming you have copied the source /etc/group file from your previous server to your target server, you can use the following filter to parse the group file and create commands to generate the groups and populate their members:

 # rebuild the Windows groups
 cat /etc/group | awk -F: '
 $3>100	{
 	printf("/usr/local/samba/bin/samba-tool group add %s\n", $1);
 	printf("/usr/local/samba/bin/samba-tool group addmembers %s %s\n", $1, $4);
 }' | /bin/sh

NOTE: Active Directory (and therefore Samba4) does not allow the usual Linux/Unix convention of creating private groups for users, with the same name as the user. This script does not check for these illegal group names. In this case, the samba-tool command will simply fail and skip over these groups, leaving you with just the valid groups. It may be helpful to first go through your created users and either delete the group records or the corresponding users, or even rename the groups.

Rebuild Static DNS Records

By default, the conversion process makes use of the bind 9.8 (or later) DLZ "Dynamically Loaded Zone" tables. One of the primary features of this setup is that it allows DHCP based clients to securely update their own A records in DNS. There are several ways to maintain these tables once the DNS server is started (for example, by using the Windows DNS management tools), but it is helpful to be able to initially populate the static DNS records (eg., for servers with fixed IP addresses) in the zones.

Given a text file with lines similar to an old file based DNS zone table, the following script will populate the DNS records. Note that the script must be run as a user who is in the DnsAdmins group. In this case, the script only outputs the command, so you need to pipe it into a shell -- eg.: dnsbuild | sh

For example:

updates    IN  A
asterisk   IN  A
apptest    IN  A
mail       IN  A
web        IN  A
intranet   IN  CNAME    web.mydomain.org
helpdesk   IN  CNAME    web.mydomain.org
blade1     IN  A
blade2     IN  A
appdb      IN  CNAME    blade1.mydomain.org

Create the following script:

# echo commands to create (1) the reverse lookup zone, and then (2) populate
# both the forward and reverse DNS entries ("A" and "PTR" records) for
# the zones.

echo "samba-tool dns zonecreate myserver 4.10.in-addr.arpa"
cat mydnsfile.txt | awk '{printf("samba-tool dns add myserver mydomain.org %s %s %s \n", $1, $3, $4);}'

cat mydnsfile.txt | awk '
   if ($3 == "A")
     split($4, o, ".");
     printf("samba-tool dns add myserver 4.10.in-addr.arpa %d.%d PTR %s.mydomain.org\n",
                       o[4], o[3], $1)

Once you have this script, run it and pipe the results into "sh"

# dnsbuild | sh

Note that, if you run the kinit command before you run this script, then this will create a kerberos ticket for you, and you will not need to enter your password for each command (or add it to the printed commands with a "--password=..." argument).


Please share any notes about your migration here!

I kept getting messages about expired passwords, this was an early bug that has since been fixed, but if you need to extend your password times do the following:

 # samba-tool domain passwordsettings set --max-pwd-age=999