Introduction

This guide is only relevant if you have a Samba NT4-style domain, that you want to upgrade to Samba Active Directory!

Many people find themselves in a situation where they have an existing Samba NT4-style domain, complete with an extensive set of domain users, groups and machines. The domain is functioning rather well, but they find themselves running into more and more dead ends. Things that a NT4-style domain just doesn't support.

Samba provides a way to migrate an existing NT4-style domain to a new Samba Active Directory. The following guide describes the upgrade scenario. It is suitable for upgrading an existing Samba installation, as well as running the migrating on a new server, if you had considered e.g. replacing the hardware at the same time.

About classicupgrade

The classicupgrade is a function built into samba-tool. The intent of this function is to do a full replacement of an existing Samba NT4-style domain. It is possible to do the conversion and the users and machines will simply re-connect to the new Samba AD installation without needing to manually re-join.

Doing a classicupgrade is possible from all passwd backends (smbpasswd, tdbsam and ldapsam).

Important notes before you start

The migration from an NT4-style domain to Active Directory is one way! This means that once your clients contact your migrated AD Domain Controller, they will never be able to access the NT4-style domain again - even if you roll back your changes!

It's highly recommended, that before you do the migration, you should test the upgrade process in a separate network from your production! This enables you to avoid unnecessary downtime through unpredictable problems and it won't have any effect on your existing network.

It used to be thought that using Windows RIDs for Unix IDs was acceptable, time has proven otherwise. If you have users and groups that use their Windows RID for their Unix ID (uidNumber or gidNumber), you should consider changing these before carrying out the upgrade. You should also consider removing any Unix IDs (uidNumber or gidNumber) from the 'Well known SIDs', except for the 'Domain Users' group.

Server information used in this HowTo

Inside this HowTo, we will be using the following configuration/settings:

Preparations

Upgrading on a new server

If you had chosen to migrate to Samba Active Directory on a different machine, some further steps of preparation are required.

LDAP

If the backend of your PDC is ldapsam, you have the choice of:

allowing the LDAP backend to stay on it's current host, as it is only required for the classicupgrade. Samba AD is shipped with its own LDAP server and won't use the external LDAP server. In this case, make sure that you check/adapt your configuration (ldap.conf, smb.conf) to retrieve the information from your old LDAP backend host.

install a temporary openLDAP backend on the new host, import the content of your current installation and after the classicupgrade, shut it down. The following is just a basic set of steps, typically required for this procedure. Consult your distributions documentation for specific requirements.

Samba

You also need to transfer several databases and the smb.conf of your old PDC to the new host, as well. The classicupgrade process section will tell you later about everything needed. You just have to copy the required files to the new server before.

Avoiding common problems

Prevent failure due to duplicate SID's

A common problem is duplicate SID's in the backend. In a healthy environment, a SID is unique. However, old Samba versions without sanity checks, wrong manual changes or other things, could have allowed duplicate SID's in your environment. These need to be fixed/removed. Otherwise the classicupgrade is not possible!

If any of your users have a RID less than '1000' and you wish them to exist in the new AD domain, you will need to change their RID, see below for how to do this.

Prevent failure due to common user/group names

If you have any usernames that are the same as a groupname, you will have to rename one of them. Otherwise the provisioning will fail („ProvisioningError: Please remove common user/group names before upgrade.“). Also, if you have unique groups that, for whatever historical reason, share the same displayName, they will have to be edited so that all the displayNames are different.

slapd.conf sizelimit

Note: The following is only relevant in passdb backend = ldapsam setups:

If you have many objects in your PDC LDAP, you should consider adding

sizelimit {<integer>|unlimited}

to your slapd.conf. This parameter specifies the maximum number of entries returned from a search operation. The default, if not set, is 500. This can cause problems, when having many objects in your LDAP directory and classicupgrade can't retrieve them all!

Active Directory Domain Name

Choose a meaningful and suitable Active Directory domain name / realm. See DNS best practice.

Note: Currently Samba does not provide capabilities to change the AD Domain Name afterwards!

Domain Controller name

If you need to change the Domain Controller name during the migration, simply edit the old PDC smb.conf file that the classicupgrade will use for doing the migration and set/change the netbios name:

netbios name = DC1

Though it's possible to rename a DC afterwards, it is always additional work and can cause problems (forgotten configuration adaptations, etc.).

The netbios name set in smb.confmust match the short hostname the Domain Controller will run on.

Installing Samba

Versions

This HowTo is frequently updated to reflect the latest changes. Please see the Samba Release Planning for more specifics.

Paths

Take care when running Samba commands, if you also have a previous version of Samba installed. To avoid inadvertently running the wrong version, you should consider putting the /usr/local/samba/bin/ and /usr/local/samba/sbin/ directories in the beginning of your $PATH variable!

You can see what version of Samba, if any, is in your $PATH variable, by running:

# samba --version

The classicupgrade process

Before you start, If you are carrying out the upgrade on the same server as your NT4-style domain PDC, you should shutdown your Samba PDC services (smbd, nmbd, winbind), but leave your LDAP server running (if using passwd backend = ldapsam). If you are carrying out the upgrade on a new Computer, you should also stop any running Samba services.

Rename your Samba PDC installation directory, or at least the folder containing the databases, to avoid mixing binaries/libraries/databases from the old and new installation:

# mv /usr/local/samba/ /usr/local/samba.PDC/

It will also prevent problems that could happen, if your old Samba installation is started automatically at boot time again.

Rename your smb.conf to a name indicating that it's the one from your old PDC:

The classicupdate process uses information from databases of your old PDC installation. That's why it is necessary to have them all in one directory. Copy the following databases from your old PDC installation to a new folder. We'll use /usr/local/samba.PDC/dbdir/ in this guide:

The classicupgrade will setup a database based on the Samba NT4-style domain SID. A default directory layout is created including accounts, groups, ACLs, etc. Imports of e.g. user and machine accounts are done.

The classicupgrade step must be run as user root. Otherwise you will get permission denied errors!

--dbdir= Path to samba classic DC directory, containing all databases required for
the migration
--realm= Set the realm name
--dns-backend= Optional.
Required if BIND9_DLZ should be used as DNS backend.
Default is the internal DNS (SAMBA_INTERNAL)
Optional:
If you have multiple NICs, classicupgrade auto-chooses the IPv4/v6 address of one NIC to setup
the Domain Controller.
To prevent this, add the following parameters to the classicupgrade command. This will bind Samba to
the given interface (eth0) and localhost (Samba should always listen on localhost too).
--option="interfaces=lo eth0" --option="bind interfaces only=yes"

The following is a sample output of a successful classicupgrade. Depending on your database backend, Samba version and other factors, the output will differ:

If your passdb backend was smbpasswd or tdbsam, remove the domain groups from /etc/group. All groups that had a groupmapping were imported, including their members. You should also remove any Samba users from /etc/passwd, they are now stored in AD.

If you used the internal DNS server, you will need to add a dns forwarder line to smb.conf, such as dns forwarder = 8.8.8.8.

Continuing with the AD DC setup

The „classicupdate“ process replaces the „provisioning“ step in the Samba AD DC HowTo. If the classicupgrade finished without problems, you have to continue with the Samba AD DC HowTo after the provisioning step.

Improving classicupgrade

Because of complexity and the various setups, the classicupgrade doesn't catch all exceptions with a meaningful message yet.

Please open a bug report for every uncaught exception error (please first search bugzilla, to see if it has already been reported).

Of course all other bugs, feature enhancements, etc. should be reported, as well, to improve the migration process in future releases.

classicupgrade FAQ

What are the consequences of changing a SID/RID?

Warning: SID's are the only thing that Windows uses in it's backend to identify users, groups and machines. Changing a SID, without due consideration, may result in serious problems or damages!

Example 1: You have two accounts with the same SID. One of them is member of the local administrators group on a workstation. If you change the SID of this account, the group membership gets lost, because Windows had stored the account SID in the group and not the account name.

Example 2: You have two machine accounts with the same SID. If you change the SID of one account, then this computer is not part of the domain any more and logins are not possible. If you have duplicate SID's and at least one of them is on a machine account, the easiest way is to delete the machine account and rejoin the computer to the domain.

Error: User 'Administrator' in your existing directory has SID ..., expected it to be ...-500

Not all attributes were copied when migrating from passwd backend = ldapsam

Sadly classicupdate currently does not migrate all attributes found in LDAP. You can follow bug report #9908 about the progress. But improvements would only take effect when doing the classicupgrade - not afterwards!

Workaround:

Change the listen port of your NT4-style domain LDAP server to a different one than its default (389/tcp), if hosted on the same machine as your new Active Directory.

Write a small script, that walks through all user accounts in your AD, then search the same user account in your old LDAP and retrieve the attributes you want to transfer. Add them to an LDIF file, which can be imported with