Migrating a Samba NT4 Domain to Samba AD (Classic Upgrade): Difference between revisions

From SambaWiki
(Added FAQ to classic upgrade page)
(Complete and comprehensive re-write of the classicupgrade HowTo)
Line 1: Line 1:
= Introduction =
'''PRENOTE''' This guide is only for replacing the "Provision Samba4" step on the main [[Samba AD DC HOWTO]] wiki page. Please follow that page in full detail before attempting anything on this page.


'''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 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.


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.
The following is a HOWTO for the Samba3 to Samba4 upgrade process.


Samba provides a way to migrate an existing NT4-style domain to a new Samba Active Directory. The following guide describes the upgrade szenario.








= Samba Tool =


= About classicupgrade =
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.
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). But only ldapsam enables the automatic import of groups, as well. For the other backends this has to be done [[#Manual_import_of_groups_.28only_smbpasswd_and_tdbsam_passdb_backend.29|manually]], what results in new SIDs for these groups. See: [[#What_are_the_consequences_changing_an_SID.2FRID.3F|What are the consequences changing an SID/RID?]]
'''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.






= Important notes before you start =
== Notes about migrating from LDAP backend ==


'''The migration from an NT4-style domain to Active Directory is a one way road! This means that when your <u>clients are contacting the first time your migrated AD Domain Controller, then will never access the NT4-style domain any more</u> - even if you rollback your changes!'''
Make sure you have the ldap headers (apt-get install libldap2-dev for debian based distros)


'''It's highly recommended, that <u>before you do the migration</u>, you should test the upgrade process in a network, that is separated from your production! This enables you to avoid unnecessary downtimes through unpredictable problems and it won't have any effects to your existing network.'''
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.






=== Duplicate SIDs ===
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.'''


= Server information used in this HowTo =

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

AD DC Installation Directory: /usr/local/samba/
AD DC Hostname: DC1
AD DNS Name: samdom.example.com
Realm: samdom.example.com
NT4 Domain Name: samdom
IP Address: 192.168.1.1
Databases of the Samba NT4-domain: /usr/local/samba.PDC/private/
smb.conf of the Samba NT4-domain: /usr/local/samba.PDC/etc/smb.PDC.conf





= Preparations =

== Avoiding common problems ==

=== Prevent duplicate SIDs abortions ===

A common problem are duplicate SIDs in the backend. In a healthy environment an [https://en.wikipedia.org/wiki/Security_Identifier SID] is unique. But old Samba versions without sanity checks, wrong manual changes or other things could have lead to duplicate SIDs in your environment. These need to be fixed/removed. Otherwise the classicupgrade is not possible!

See: [[#What_are_the_consequences_changing_an_SID.2FRID.3F|What are the consequences changing an SID/RID?]]

To detect duplicate SIDs in an LDAP backend, you can use the following script on your LDAP server:


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


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.
To find duplicate SIDs on other passdb backends (smbpasswd, tdbsam), you have to script around the output of the following two commands:


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


To change SIDs for for groups, remove the mapping and re-add it. A new SID with the next free RID is created and used.


''Note: This is is only relevant if you are using „passdb backend = ldapsam“. For other backends the groups are not imported and need to [[#Manual_import_of_groups_.28only_smbpasswd_and_tdbsam_passdb_backend.29|manually]] re-created in Active Directory. This automatically would lead into new SIDs.''


# net groupmap delete ntgroup="demo group"
=== Installing on a new server (recomended but tedious) ===
Sucessfully removed demo group from the mapping db
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
# net groupmap add ntgroup="Demo Group" unixgroup="demo group"
No rid or sid specified, choosing a RID
Got RID 1009
Successfully added group Demo Group to the mapping db as a domain group


For user and machine accounts, you have to manually assign a new RID:
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


# net maxrid
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.)
Currently used maximum rid: 3001
# pdbedit -U 3002 -u demo1
...
User SID: S-1-5-21-4097619914-84555263-3210783664-3002






=== Prevent common user/group name abortions ===
=== Final notes ===


If you are having any usernames, that are the same than a groupname, you have to rename one of them. Otherwise the provisioning will fail („ProvisioningError: Please remove common user/group names before upgrade.“).
['''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'''.]


''Note: This is is only relevant if you are using „passdb backend = ldapsam“. For other backends the groups are not imported and need to [[#Manual_import_of_groups_.28only_smbpasswd_and_tdbsam_passdb_backend.29|manually]] re-created in Active Directory. This automatically would lead into new SIDs.''
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


= Upgrading =
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.


=== slapd.conf sizelimit ===
'''First:''' Download, build and install the Samba4 binaries, either from one of the releases or from "git". On the [[Samba4/HOWTO]] page, follow the first three steps, stopping before the '''provision''' step.


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


If you have many objects in your PDC LDAP, you should consider to add
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!


== 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/


== Active Directory Domain Name ==
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.


Choose a meaningful and suitable Active Directory domain name / realm. See [[Domain_Name_best_practice|Domain Name best practice]].
If you wish to change the host name of the new server, you can change the netbios name in the Samba3 conf file.


''Note: Currently Samba does not provide capabilities to change the AD Domain Name afterwards!''
['''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".''


== Domain Controller name ==


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


netbios name = DC1
== 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.


Though it's possible to rename a DC afterwards, it is always additional work and can cause problems (forgotten configuration adaptations, etc.)
'''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


Options:
* 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.


= Installing Samba =
<u>DNS Backend:</u> Per default Samba is provisioned with the internal DNS server. If you want to use Bind as backend, add --dns-backend=BIND9_DLZ. Bind as backend is recommended if you plan to create a complexer DNS setup, than the Samba 4 internal DNS currently allows. Find information on how to setup and configure Bind as backend, here: [[DNS_Backend_BIND|Bind DNS backend HowTo]].


== Versions ==
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.


This HowTo is frequently updated to reflect the latest changes. Please see the [[Samba_Release_Planning|Samba Release Planning]] for more specifics.
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)


== Different ways to install ==
* '''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.


You have a few options to install Samba:
* Also, this is a good point to make sure that both the Samba4 service and the new DNS service DO start on boot.


* [[Build_Samba|Build Samba]] by yourself.


* Install [[Binary_Distribution_Packages|binary distribution packages]]. Make sure, that you use a recent Samba installation with Active Directory Domain Controller capabilities!


:* Install from [http://www.enterprisesamba.com/samba/ SerNet Enterprise Samba] package.


See [[OS Requirements|OS Requirements]] for dependencies and recommendations.
= 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:


== Paths ==
# 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


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!
'''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.


You can see what version of Samba, if any, is in your $PATH variable, by running:
= Rebuild Static DNS Records =
# samba --version
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 10.4.1.4
asterisk IN A 10.4.1.7
apptest IN A 10.4.1.8
mail IN A 10.4.1.226
web IN A 10.4.0.67
intranet IN CNAME web.mydomain.org
helpdesk IN CNAME web.mydomain.org
blade1 IN A 10.4.0.227
blade2 IN A 10.4.0.229
appdb IN CNAME blade1.mydomain.org


Create the following script:



#!/bin/sh
= The classicupgrade process=
#-------------------

# echo commands to create (1) the reverse lookup zone, and then (2) populate
Before you start, shutdown your Samba PDC services (smbd, nmbd, winbind), but leave your LDAP server running (if using passwd backend = ldapsam).
# both the forward and reverse DNS entries ("A" and "PTR" records) for

# the zones.
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, like they will happen, when 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:

# mv /usr/local/samba.PDC/etc/smb.conf /usr/local/samba.PDC/etc/smb.PDC.conf

The classicupgrade 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're getting permission denied errors!

To start the <u>classicupgrade with [[DNS#Internal_DNS|Internal DNS]] setup</u>, run:

# samba-tool domain classicupgrade --dbdir=/usr/local/samba.PDC/private/ --use-xattrs=yes --realm=samdom.example.com --dns-backend=SAMBA_INTERNAL /usr/local/samba.PDC/etc/smb.PDC.conf

To start the <u>classicupgrade with [[DNS#BIND_DLZ_plug-in_.28for_BIND_9.8_and_9.9.29|BIND_DLZ DNS]] setup</u>, run:
# samba-tool domain classicupgrade --dbdir=/usr/local/samba.PDC/private/ --use-xattrs=yes --realm=samdom.example.com --dns-backend=BIND9_DLZ /usr/local/samba.PDC/etc/smb.PDC.conf

<u>Parameter explanations:</u>
--dbdir= Path to samba classic DC database directory
--use-xattrs=yes Use the native filesystem capabilities for storing the neccessary extended attributes for Windows ACLs (required e. g. for the SysVol share)
--realm= Set the realm name
--dns-backend= Optional. Required if [[DNS_Backend_BIND|BIND9_DLZ should be used as DNS backend]]. Default is the internal DNS (SAMBA_INTERNAL)
Optional:
echo "samba-tool dns zonecreate myserver 4.10.in-addr.arpa"
If you are having multiple NICs, classicupgrade auto-chooses the IPv4/v6 address of one NIC to setup the Domain Controller.
cat mydnsfile.txt | awk '{printf("samba-tool dns add myserver mydomain.org %s %s %s \n", $1, $3, $4);}'
To prevent this, add the following to parameters the the classicupgrade command. This would bind Samba to the given
interface (eth0) and localhost (Samba should always listen on localhost, too).
cat mydnsfile.txt | awk '
--option="interfaces=lo eth0" --option="bind interfaces only=yes"
{

if ($3 == "A")
The following is a <u>sample</u> output of a successfull classicupgrade. Depending on your database backend, Samba version and other factors, the output will differ:
{

split($4, o, ".");
Reading smb.conf
printf("samba-tool dns add myserver 4.10.in-addr.arpa %d.%d PTR %s.mydomain.org\n",
Provisioning
o[4], o[3], $1)
Exporting account policy
}
Exporting groups
}'
Exporting users
Next rid = 1010
Exporting posix attributes
Reading WINS database
Cannot open wins database, Ignoring: [Errno 2] No such file or directory: '/usr/local/samba.PDC/private/wins.dat'
Looking up IPv4 addresses
Looking up IPv6 addresses
No IPv6 address will be assigned
Setting up share.ldb
Setting up secrets.ldb
Setting up the registry
Setting up the privileges database
Setting up idmap db
Setting up SAM db
Setting up sam.ldb partitions and settings
Setting up sam.ldb rootDSE
Pre-loading the Samba 4 and AD schema
Adding DomainDN: DC=samdom,DC=example,DC=com
Adding configuration container
Setting up sam.ldb schema
Setting up sam.ldb configuration data
Setting up display specifiers
Modifying display specifiers
Adding users container
Modifying users container
Adding computers container
Modifying computers container
Setting up sam.ldb data
Setting up well known security principals
Setting up sam.ldb users and groups
Setting up self join
Setting acl on sysvol skipped
Adding DNS accounts
Creating CN=MicrosoftDNS,CN=System,DC=samdom,DC=example,DC=com
Creating DomainDnsZones and ForestDnsZones partitions
Populating DomainDnsZones and ForestDnsZones partitions
See /usr/local/samba/private/named.conf for an example configuration include file for BIND
and /usr/local/samba/private/named.txt for further documentation required for secure DNS updates
Setting up sam.ldb rootDSE marking as synchronized
Fixing provision GUIDs
A Kerberos configuration suitable for Samba 4 has been generated at /usr/local/samba/private/krb5.conf
Setting up fake yp server settings
Once the above files are installed, your Samba4 server will be ready to use
Server Role: active directory domain controller
Hostname: DC1
NetBIOS Domain: SAMDOM
DNS Domain: samdom.example.com
DOMAIN SID: S-1-5-21-4097619914-84555263-3210783664
Importing WINS database
Importing Account policy
Importing idmap database
Cannot open idmap database, Ignoring: [Errno 2] No such file or directory
Adding groups
Importing groups
Commiting 'add groups' transaction to disk
Adding users
Importing users
Commiting 'add users' transaction to disk
Adding users to groups
Commiting 'add users to groups' transaction to disk
Setting password for administrator

'''Note:''' <u>If you re-run the classicupgrade</u>, you need to remove the auto-generated smb.conf and the databases:

# rm -f /usr/local/samba/etc/smb.conf
# rm -rf /usr/local/samba/private/*





= After the classicupgrade =

* Shutdown your LDAP server, if your passdb backend was ldapsam. Samba Active Directory requires to start its own LDAP server, that binds to the [[Samba_port_usage#Port_usage_when_Samba_runs_as_DC|default ports port 389/tcp (LDAP) and 636/tcp (LDAPS)]].

* Disable the automatic start of your Samba PDC and LDAP server (if any).

* Enable your Samba AD service to automatically start at boot time.

* If your passdb backend was smbpasswd or tdbsam, you have to [[#Manual_import_of_groups_.28only_smbpasswd_and_tdbsam_passdb_backend.29|manually import your groups]].





= Manual import of groups (only smbpasswd and tdbsam passdb backend) =

When using the passdb backends smbpasswd or tdbsam, it is not possible to automatically import groups from /etc/group during the classicupgrade. This has to be done manually afterwards.

'''Important note:''' Please read [[#What_are_the_consequences_changing_an_SID.2FRID.3F|What are the consequences changing an SID/RID?]]

The following small script create all groups from /etc/group with an GID > 1000 in Active Directory and add their members to it:

cat /etc/group | awk -F: '$3 > 1000 {
printf("samba-tool group add \"%s\"\n", $1);
printf("samba-tool group addmembers \"%s\" %s\n", $1, $4);
}' | /bin/sh





= Continuing with the AD DC setup =

The „classicupdate“ process replaces the „provisioning“ step in the Samba AD DC HowTo. If you had finished the classicupgrade without problems, you have to continue with the Samba AD DC HowTo [[Samba_AD_DC_HOWTO#Starting_Your_Samba_AD_DC|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 [https://bugzilla.samba.org/ bug report] for every uncaught exception error (please first [https://bugzilla.samba.org/query.cgi search bugzilla], if it was already reported).

Of course all other bugs, feature enhancements, etc. should be [https://bugzilla.samba.org/ reported], as well, to improve the migration process in future releases.





= classicupgrade FAQ =

== What are the consequences changing an SID/RID? ==

'''Warning:''' Windows uses in it's backend only SIDs to identify users, groups and machines. Changing an 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 SIDs 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.


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


# dnsbuild | sh


== Error: User 'Administrator' in your existing directory has SID ..., expected it to be ...-500 ==
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).


The error says what's wrong: In your NT4-style domain backend, the RID of the domain administrator account isn't -500, what it should be (see. [http://support.microsoft.com/kb/243330/en Windows well-known security identifiers]). Change it to 500 and start over. You can remove the account, too, as it will be automatically created during the AD provisioning. See: [[#What_are_the_consequences_changing_an_SID.2FRID.3F|What are the consequences changing an SID/RID?]]
= Notes =
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




== 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 [https://bugzilla.samba.org/show_bug.cgi?id=9008 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 than your new Active Directory.
= FAQ =


* Write a small script, that walks trought 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
== User 'Administrator' in your existing directory has SID ..., expected it to be ...-500 ==


# ldbmodify -H path/to/sam.ldb LDIFfilename
The error says what's wrong: In your NT4-style domain backend, the RID of the domain administrator account isn't 500, what it should be (see. [http://support.microsoft.com/kb/243330/en Windows well-known security identifiers]). Change it to 500 and start over. You can remove the account, too, as it will be automatically created during the AD provisioning.

Revision as of 10:42, 28 May 2014

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 szenario.



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). But only ldapsam enables the automatic import of groups, as well. For the other backends this has to be done manually, what results in new SIDs for these groups. See: What are the consequences changing an SID/RID?



Important notes before you start

The migration from an NT4-style domain to Active Directory is a one way road! This means that when your clients are contacting the first time your migrated AD Domain Controller, then will never access the NT4-style domain any more - even if you rollback your changes!

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



Server information used in this HowTo

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

AD DC Installation Directory:       /usr/local/samba/
AD DC Hostname:                     DC1
AD DNS Name:                        samdom.example.com
Realm:                              samdom.example.com
NT4 Domain Name:                    samdom
IP Address:                         192.168.1.1
Databases of the Samba NT4-domain:  /usr/local/samba.PDC/private/
smb.conf of the Samba NT4-domain:   /usr/local/samba.PDC/etc/smb.PDC.conf



Preparations

Avoiding common problems

Prevent duplicate SIDs abortions

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

See: What are the consequences changing an SID/RID?

To detect duplicate SIDs in an LDAP backend, you can use the following script on your LDAP server:

#!/usr/bin/python
# A quick and dirty python script that checks for duplicat SID's using slapcat.
import os

data = os.popen("slapcat 2>&1 | 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:
        line.append(each_line.strip())

anydup(line)

To find duplicate SIDs on other passdb backends (smbpasswd, tdbsam), you have to script around the output of the following two commands:

# pdbedit -Lv
# net groupmap list

To change SIDs for for groups, remove the mapping and re-add it. A new SID with the next free RID is created and used.

Note: This is is only relevant if you are using „passdb backend = ldapsam“. For other backends the groups are not imported and need to manually re-created in Active Directory. This automatically would lead into new SIDs.

# net groupmap delete ntgroup="demo group"
Sucessfully removed demo group from the mapping db

# net groupmap add ntgroup="Demo Group" unixgroup="demo group"
No rid or sid specified, choosing a RID
Got RID 1009
Successfully added group Demo Group to the mapping db as a domain group

For user and machine accounts, you have to manually assign a new RID:

# net maxrid
Currently used maximum rid: 3001

# pdbedit -U 3002 -u demo1
...
User SID:   S-1-5-21-4097619914-84555263-3210783664-3002


Prevent common user/group name abortions

If you are having any usernames, that are the same than a groupname, you have to rename one of them. Otherwise the provisioning will fail („ProvisioningError: Please remove common user/group names before upgrade.“).

Note: This is is only relevant if you are using „passdb backend = ldapsam“. For other backends the groups are not imported and need to manually re-created in Active Directory. This automatically would lead into new SIDs.


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 to add

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 Domain Name best practice.

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


Domain Controller name

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

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.)



Installing Samba

Versions

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


Different ways to install

You have a few options to install Samba:

  • Install binary distribution packages. Make sure, that you use a recent Samba installation with Active Directory Domain Controller capabilities!

See OS Requirements for dependencies and recommendations.


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, shutdown your Samba PDC services (smbd, nmbd, winbind), but leave your LDAP server running (if using passwd backend = ldapsam).

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, like they will happen, when 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:

# mv /usr/local/samba.PDC/etc/smb.conf /usr/local/samba.PDC/etc/smb.PDC.conf

The classicupgrade 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're getting permission denied errors!

To start the classicupgrade with Internal DNS setup, run:

# samba-tool domain classicupgrade --dbdir=/usr/local/samba.PDC/private/ --use-xattrs=yes --realm=samdom.example.com --dns-backend=SAMBA_INTERNAL /usr/local/samba.PDC/etc/smb.PDC.conf

To start the classicupgrade with BIND_DLZ DNS setup, run:

# samba-tool domain classicupgrade --dbdir=/usr/local/samba.PDC/private/ --use-xattrs=yes --realm=samdom.example.com --dns-backend=BIND9_DLZ /usr/local/samba.PDC/etc/smb.PDC.conf

Parameter explanations:

--dbdir=                 Path to samba classic DC database directory
--use-xattrs=yes         Use the native filesystem capabilities for storing the neccessary extended attributes for Windows ACLs (required e. g. for the SysVol share)
--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 are having multiple NICs, classicupgrade auto-chooses the IPv4/v6 address of one NIC to setup the Domain Controller.
To prevent this, add the following to parameters the the classicupgrade command. This would 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 successfull classicupgrade. Depending on your database backend, Samba version and other factors, the output will differ:

Reading smb.conf
Provisioning
Exporting account policy
Exporting groups
Exporting users
Next rid = 1010
Exporting posix attributes
Reading WINS database
Cannot open wins database, Ignoring: [Errno 2] No such file or directory: '/usr/local/samba.PDC/private/wins.dat'
Looking up IPv4 addresses
Looking up IPv6 addresses
No IPv6 address will be assigned
Setting up share.ldb
Setting up secrets.ldb
Setting up the registry
Setting up the privileges database
Setting up idmap db
Setting up SAM db
Setting up sam.ldb partitions and settings
Setting up sam.ldb rootDSE
Pre-loading the Samba 4 and AD schema
Adding DomainDN: DC=samdom,DC=example,DC=com
Adding configuration container
Setting up sam.ldb schema
Setting up sam.ldb configuration data
Setting up display specifiers
Modifying display specifiers
Adding users container
Modifying users container
Adding computers container
Modifying computers container
Setting up sam.ldb data
Setting up well known security principals
Setting up sam.ldb users and groups
Setting up self join
Setting acl on sysvol skipped
Adding DNS accounts
Creating CN=MicrosoftDNS,CN=System,DC=samdom,DC=example,DC=com
Creating DomainDnsZones and ForestDnsZones partitions
Populating DomainDnsZones and ForestDnsZones partitions
See /usr/local/samba/private/named.conf for an example configuration include file for BIND
and /usr/local/samba/private/named.txt for further documentation required for secure DNS updates
Setting up sam.ldb rootDSE marking as synchronized
Fixing provision GUIDs
A Kerberos configuration suitable for Samba 4 has been generated at /usr/local/samba/private/krb5.conf
Setting up fake yp server settings
Once the above files are installed, your Samba4 server will be ready to use
Server Role:           active directory domain controller
Hostname:              DC1
NetBIOS Domain:        SAMDOM
DNS Domain:            samdom.example.com
DOMAIN SID:            S-1-5-21-4097619914-84555263-3210783664
Importing WINS database
Importing Account policy
Importing idmap database
Cannot open idmap database, Ignoring: [Errno 2] No such file or directory
Adding groups
Importing groups
Commiting 'add groups' transaction to disk
Adding users
Importing users
Commiting 'add users' transaction to disk
Adding users to groups
Commiting 'add users to groups' transaction to disk
Setting password for administrator

Note: If you re-run the classicupgrade, you need to remove the auto-generated smb.conf and the databases:

# rm -f /usr/local/samba/etc/smb.conf
# rm -rf /usr/local/samba/private/*



After the classicupgrade

  • Disable the automatic start of your Samba PDC and LDAP server (if any).
  • Enable your Samba AD service to automatically start at boot time.



Manual import of groups (only smbpasswd and tdbsam passdb backend)

When using the passdb backends smbpasswd or tdbsam, it is not possible to automatically import groups from /etc/group during the classicupgrade. This has to be done manually afterwards.

Important note: Please read What are the consequences changing an SID/RID?

The following small script create all groups from /etc/group with an GID > 1000 in Active Directory and add their members to it:

cat /etc/group | awk -F: '$3 > 1000 {
      printf("samba-tool group add \"%s\"\n", $1);
      printf("samba-tool group addmembers \"%s\" %s\n", $1, $4);
  }' | /bin/sh



Continuing with the AD DC setup

The „classicupdate“ process replaces the „provisioning“ step in the Samba AD DC HowTo. If you had finished the classicupgrade 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, if it was already 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 changing an SID/RID?

Warning: Windows uses in it's backend only SIDs to identify users, groups and machines. Changing an 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 SIDs 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

The error says what's wrong: In your NT4-style domain backend, the RID of the domain administrator account isn't -500, what it should be (see. Windows well-known security identifiers). Change it to 500 and start over. You can remove the account, too, as it will be automatically created during the AD provisioning. See: What are the consequences changing an SID/RID?


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 than your new Active Directory.
  • Write a small script, that walks trought 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
# ldbmodify -H path/to/sam.ldb LDIFfilename