Debian LDAP Migration Tools

Migrating /etc Flat File Databases to LDAP (Authentication and Name Services) using migrationtools package in Debian 3.1 (Sarge)

i. Install the LDAP migration tools

Do 'apt-get install migrationtools' (at least for 'Sarge'). This will install a collection of scripts in /usr/share/migrationtools

ii. Edit migrationtools configuration file

Edit /etc/migrationtools/ by changing the lines show below. The DEFAULT_ changes are customisations for your site, while the UID/GID lines ignore system users (that is those users created and modified by debian package scripts), and the nobody user and group (65534:65534)


 # Default DNS domain
 $DEFAULT_MAIL_DOMAIN = "your.domain";
 # Default base
 $DEFAULT_BASE = "[BaseDN]";
 # Uncomment these to exclude Debian-managed system users and groups

 # And here's the opposite for completeness


 # Default DNS domain
 # Default base
 $DEFAULT_BASE = "dc=example,dc=com";
 # Uncomment these to exclude Debian-managed system users and groups

 # And here's the opposite for completeness

For Samba LDAP Users

The default subtrees used for user and group information are not compatible with the smbldap-tools package which is recommended when using LDAP for Samba authentication and mapping. For that reason, if you are using Samba with LDAP you should make the following additional changes to /etc/migrationtools/

 $NAMINGCONTEXT{'passwd'}            = "ou=Users";
 $NAMINGCONTEXT{'group'}             = "ou=Groups";

Optional: Use different subtrees based on function

If you are doing more than LDAP Authentication with your server you may wish to divide the various functions of the LDAP server into different subtrees. This can also be important if you are using different servers for different LDAP functions but still want the tree to look like it is coming from a single source (it can be done but is not discussed here).

In my examples, I have 'ou=dns,[BaseDN] for the DNS server, 'ou=auth,[BaseDN]' for users and groups (authentication/authorization), 'ou=mail,[BaseDN]' for email related information, 'ou=syscfg,[BaseDN]' for system configuration information (like /etc/fstab), and 'ou=net,[BaseDN]' for networking configuration info handled by NSS.

The following assumes you also need to make the changes above for smbldap-tools,

 } else {
         $NAMINGCONTEXT{'aliases'}           = "ou=Aliases,ou=mail";
         $NAMINGCONTEXT{'fstab'}             = "ou=Mounts,ou=syscfg";
         $NAMINGCONTEXT{'passwd'}            = "ou=Users,ou=auth";
         $NAMINGCONTEXT{'netgroup_byuser'}   = "nisMapName=netgroup.byuser,ou=auth";
         $NAMINGCONTEXT{'netgroup_byhost'}   = "nisMapName=netgroup.byhost,ou=auth";
         $NAMINGCONTEXT{'group'}             = "ou=Groups,ou=auth";
         $NAMINGCONTEXT{'netgroup'}          = "ou=Netgroup,ou=auth";
         $NAMINGCONTEXT{'hosts'}             = "ou=Hosts,ou=net";
         $NAMINGCONTEXT{'networks'}          = "ou=Networks,ou=net";
         $NAMINGCONTEXT{'protocols'}         = "ou=Protocols,ou=net";
         $NAMINGCONTEXT{'rpc'}               = "ou=Rpc,ou=net";
         $NAMINGCONTEXT{'services'}          = "ou=Services,ou=net";

You will also need to makes the following changes to the 'sub ldif_entry' function in the same file /etc/migrationtools/

 sub ldif_entry
 # remove leading, trailing whitespace
         local ($HANDLE, $lhs, $rhs) = @_;
         local ($type, $val) = split(/\=/, $lhs);
         local ($dn);
         local (@newval);
         if ($val =~ /\,/) {
                 @newval = split(/\,/, $val);
                 $val = $newval[0];


Apparently EXTENDED_SCHEMA is set to '1' in many other documents. This probably will not work without modification under Debian 3.1 'Sarge'. I haven't tried going all the way, however I have looked at the ldif that would be used and appears the following note applies.

Note: Debian doesn't include a kerberos.schema, so one must manually edit passwd.ldif to remove the two lines refering to kerberos for every user. That is, the following two lines:

 objectClass: kerberosSecurityObject
 krbName: user@YOUR.DOMAIN

Where user@YOUR.DOMAIN is the username with @YOUR.DOMAIN appended.

iii. Perform the Migration

If you just want LDAPAuthentication you probably want option 3, migrating only the /etc/passwd and /etc/group databases (but first using


  • You may need to create higher–level nodes in the tree before you perform the imports
  • For example to import /etc/passwd using the settings above you would need ou=auth,[BaseDN]
  • To create a node that only exists so that nodes can exist beneath it (i.e. an internal vertex), you could use 'ldapadd -h localhost -x -W -D "cn=admin,{BaseDN}" -c -f node.ldif' for the following node.ldif
  • The and scripts will create most of the required internal vertices (specifically the nodes indicated by $NAMING_CONTEXT in /etc/migrationtools/ You should only need to create extra nodes if you choose to use separate subtrees for different functions (e.g. if you use ou=Users,ou=auth for /etc/passwd you will likely need to create ou=auth but not ou=Users)


 # node, [BaseDN]
 dn: ou=node,[BaseDN]
 objectClass: top
 objectClass: organizationalUnit
 objectClass: domainRelatedObject
 associatedDomain: your.domain
 ou: node


 # auth, example, com
 dn: ou=auth,dc=example,dc=com
 objectClass: top
 objectClass: organizationUnit
 objectClass: domainRelatedObject
 ou: auth

Option 1: Just migrate everything

  1. Make sure the slapd service is started
  2. Confirm that /etc/ldap/ldap.conf is correctly configured
  3. cd /usr/share/migrationtools
  4. Execute './migrate_all_online', answering the following questions: normally you can just accept the defaults
    1. Enter the X.500 naming context you wish to import into: dc=your,dc=domain
      • Here you should enter the BaseDN for your LDAP tree
    2. Enter the hostname of your LDAP server [ldap]:
    3. Enter the manager DN: [cn=admin,[BaseDN]]:
    4. (e.g. cn=admin,dc=example,dc=com)
      • And this should the LdapDn for the LDAP administrative user.
    5. Enter the credentials to bind with:
      • This should be the password for the LDAP administrative user.
    6. Do you wish to generate a DUAConfigProfile [yes|no]?
      • For most the safe answer is no as DUAConfigProfile depends on schema not included in stock Debian. The profile speeds up searching for the various flat file databases imported into LDAP in the instructions you are now reading.
      • If you are using a single LDAP server you don't really need this.
      • If you are using multiple servers for different subtrees this can help the resolution process by directing the query to the appropriate server. Describing how that works is beyond the scope of this document.
  5. If it worked, great, otherwise you may need to generate an LDIF and modify as described below.

Option 2: Migrate everything by way of a single LDIF

As Option 1, above, except,

  • slapd does not need to be started at this point
  • Execute LDAPADD="badword " ./]
  • You should get the following error messages (where the number in nis.5746.ldif will change with each run):
  •  ./ line 196: badword: command not found badword : returned non-zero exit status: saving failed LDIF to /tmp/nis.5746.ldif 
  • You can now edit /tmp/nis.5746.ldif (actually whatever file is indicated in the error message).
  • Once you think you're ready to start
  • Start the slapd daemon
  • execute (replacing [BaseDN] with your base distinguished name):
     ldapadd -D "cn=admin,[BaseDN]" -h localhost -x -W -c -f /tmp/nis.5746.ldif 
    • E.g. ldapadd -D "cn=admin,dc=example,dc=com" -h localhost -x -W -c -f /tmp/nis.5745.ldif]
  • If it worked great, otherwise you will have to correct errors, remove what was successfully added (either from the .ldif file or from the ldap server), and try again.

Synchronize the password encoding

It is not clear whether migrationtools detects the password encoding (e.g. crypt vs. md5). If it doesn't you may need to edit the ldif to use the appropriate format (e.g. if {crypt}ad$/ddd234.2s appears in the ldif but you were using md5 you may need to change the format to {md5}ad$/ddd234.2s)

This author started fresh with LDAP so he has never had to convert old /etc/passwd users, however you may be interested in the notes on PAMLDAPSetup which provides a way to convert passwords to md5 format when the password is changed (so root could elect to change all the passwords, thus getting md5 on all passwords).

Option 3: Migrate by way of an LDIF for each /etc database you want

See LDAPMigrationExamples for examples of each of the following imports.

You can migrate in a single step

You can pipe the output of migrate into ldapadd instead of redirecting to a file and using ldapadd -f filename. For example,

 ./ >base.ldif
 ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f base.ldif
would become
 ./ | ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c 

In all cases you will need to migrate some base settings

  • Execute './ >base.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,[BaseDN]" -c -f base.ldif'
  • Example commands:
     ./ >base.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f base.ldif 

Migrateable Settings and How To Import Them

Local email aliases (e.g. root mail sent to a regular user)
  • Execute './ /etc/aliases >aliases.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,[BaseDN]" -c -f aliases.ldif'
  • Example commands:
     ./ /etc/aliases >aliases.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f aliases.ldif
Filesystem Table (/etc/fstab)
  • Execute './ /etc/fstab >fstab.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,[BaseDN]" -c -f fstab.ldif'
  • Example:
     ./ /etc/fstab >fstab.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f fstab.ldif

The author doesn't use the automounter daemon so he doesn't know what is needed for this.


The author doesn't use netgroups so he doesn't know what is needed to migrate netgroup_byhost and netgroup_byuser

TCP/IP Hosts
  • Execute './ /etc/hosts >hosts.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,[BaseDN]" -c -f hosts.ldif'
  • Example:
     ./ /etc/hosts >hosts.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f hosts.ldif 
TCP/IP Networks
  • Execute './ /etc/networks >networks.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,{BaseDN}" -c -f networks.ldif'
  • Example:
     ./ /etc/networks >networks.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f hosts.ldif
TCP/IP Protocols
  • Execute './ /etc/protocols protocols.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,{BaseDN}" -c -f protocols.ldif'
  • Example:
     ./ /etc/protocols protocols.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f protocols.ldif
TCP/IP Services
  • Execute './ /etc/services >services.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,{BaseDN}" -c -f services.ldif'
  • Example:
     ./ /etc/services >services.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f services.ldif
  • Execute './ /etc/rpc >rpc.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,{BaseDN}" -c -f rpc.ldif'
  • Example:
     ./ /etc/rpc >rpc.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f rpc.ldif
Authentication: /etc/passwd
  • Execute './ /etc/passwd >passwd.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,{BaseDN}" -c -f passwd.ldif'
  • Example:
     ./ /etc/passwd >passwd.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f passwd.ldif
Authentication: /etc/group
  • Execute './ /etc/group >group.ldif'
  • Execute 'ldapadd -h localhost -x -W -D "cn=admin,{BaseDN}" -c -f group.ldif'
  • Example:
     ./ /etc/group >group.ldif
     ldapadd -h localhost -x -W -D "cn=admin,dc=example,dc=com" -c -f group.ldif

iv. Verify Data Import


 ldapsearch -x -h localhost
This should return everything in your LDAP tree except hashed passwords. If you want to see the hashed passwords as well, try
 ldapsearch -x -W -D "cn=admin,[BaseDN]" -h localhost
 ldapsearch -x -W -D "cn=admin,dc=example,dc=com" -h localhost

v. Configure System to Use LDAP

See NSSLDAPSetup.html, and PAMLDAPSetup

Previous: OpenLDAPSetupTop: LDAPNext: LDAPMigrationExamples

© 2005-2006 Daniel Dickinson <>

This document is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This document is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should be able to view a copy of the GNU General Public License at If not, you can write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA to obtain a copy.