MigrationTools.txt

   1 LDAP Migration Tools
   2
   3 The MigrationTools are a set of Perl scripts for migrating users, groups,
   4 aliases, hosts, netgroups, networks, protocols, RPCs, and services from
   5 existing nameservices (flat files, NIS, and NetInfo) to LDAP. They are
   6 located on a default installation under /usr/share/openldap/migration.
   7
   8 The tools require the ldapadd and ldif2dbm commands, which are distributed
   9 with most LDAP servers derived from the University of Michigan LDAP
  10 distribution. The source code for these is available with OpenLDAP.
  11 Additionally, Netscape provide an implementation of ldapmodify which
  12 subsumes the functionality of ldapadd. If you are using Netscape's Directory
  13 Server, you should set the $NSHOME and $serverId environment variables to
  14 assist the MigrationTools in locating your LDAP database and LDIF tools;
  15 they will use ldapmodify instead of ldapadd.
  16
  17 These tools are freely redistributable according to the license included
  18 with the source files. They may be bundled with LDAP/NIS migration products.
  19 See RFC 2307 for more information on the schema used by these scripts. THIS
  20 SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY AND WITHOUT
  21 SUPPORT.
  22
  23 Scripts
  24
  25    * migrate_base.pl creates naming context entries, including
  26      subordinate contexts such  as ou=people and ou=devices.
  27    * migrate_aliases.pl migrates aliases in /etc/aliases to entries
  28      conforming to the rfc822MailGroup schema. Organizations who have
  29      deployed LDAP-based  messaging solutions, such as Netscape's
  30      Messaging Server, may wish to use a different  schema for
  31      representing mail aliases. Ypldapd does not use X.500 groups (such
  32      as  groupOfUniqueNames) for mail alias expansion because
  33      flattening an arbitrarily nested  group at runtime may be
  34      expensive. (It is possible to write a ypldapd plug-in to support
  35      such a schema, however.)
  36    * migrate_group.pl migrates groups in /etc/group
  37    * migrate_hosts.pl migrates hosts in /etc/hosts
  38    * migrate_networks.pl migrates networks in /etc/networks
  39    * migrate_passwd.pl migrates users in /etc/passwd. Note that if
  40      users are  allowed read the userPassword attribute, and your LDAP
  41      server doesn't support  authenticating against hashed passwords
  42      then anyone may read the userPassword  attribute's value and
  43      authenticate as that user. Modern LDAP servers, such as  Netscape
  44      Directory Server, support authenticating against hashed passwords,
  45      so this is not  an issue. The OpenLDAP LDAP server also supports
  46      such authentication.
  47    * migrate_protocols.pl migrates protocols in /etc/protocols
  48    * migrate_services.pl migrates services in /etc/services
  49    * migrate_netgroup.pl migrates netgroups in /etc/netgroup
  50    * migrate_netgroup_byuser.pl migrates the netgroup.byuser map. It
  51      requires revnetgroup.
  52    * migrate_netgroup_byhost.pl migrates the netgroup.byhost map. It
  53      requires revnetgroup.
  54    * migrate_rpc.pl migrates RPCs in /etc/rpc
  55
  56 Configuration
  57
  58 The configuration  for these Perl scripts  is contained at the  head of
  59 migrate_common.ph:
  60
  61  Perl variable                  Description
  62
  63  $DEFAULT_MAIL_DOMAIN           The mail  domain used for   the mail
  64                                 attribute in  migrate_passwd.pl when
  65                                 extended schema support is enabled.  You may
  66                                 override this with the DEFAULT_MAIL_DOMAIN
  67                                 environment variable.
  68
  69  $DEFAULT_BASE                  The   naming  suffix   to  use    in
  70                                 entries'  distinguished   names.  If
  71                                 undefined, this will be constructed by
  72                                 mapping the mail domain name into a
  73                                 distinguished name (eg aceindustry.com
  74                                 becomes dc=aceindustry,dc=com ).  You may
  75                                 override this with the LDAP_BASEDN
  76                                 environment variable.
  77
  78  $EXTENDED_SCHEMA               Enables  extended  schema   support.
  79                                 This  adds the  organizationalPerson and
  80                                 inetOrgPerson object classes, amongst
  81                                 others, to users migrated by the
  82                                 migrate_passwd.pl script.
  83
  84  NAMINGCONTEXT                  Determines  the   LDAP/X.500  naming context
  85                                 to use for a migration tool.  The dictionary
  86                                 is keyed by tool (as in migrate_ tool .pl ).
  87                                 Values are concatenated with $DEFAULT_BASE
  88                                 by the & getsuffix() subroutine.
  89
  90 The  following  environment  variables  control  the  behavior  of  the
  91 migration shell scripts:
  92
  93  Environment variable           Description
  94
  95  DEFAULT_MAIL_DOMAIN            See above
  96
  97  LDAPADD                        Path  the   ldapadd executable,  for online
  98                                 migration (if not in the path or
  99                                 /usr/local/bin or /usr/bin)
 100
 101  LDIF2LDBM                      Path the  ldif2ldbm  executable, for offline
 102                                 migration (if not in the path or
 103                                 /usr/local/bin or /usr/bin)
 104
 105  PERL                           Path  to the  Perl  interpreter  (if not
 106                                 /usr/bin or /usr/local/bin)
 107
 108  LDAPHOST                       Your   LDAP   server,  for    online
 109                                 migration. This is optional; you'll be
 110                                 prompted if the environment variable is not
 111                                 set.
 112
 113  LDAP_BASEDN                    See above ( $DEFAULT_BASE).  This is
 114                                 optional; you'll be prompted if the
 115                                 environment variable is not set.
 116
 117  LDAP_BINDDN                    The distinguished  name  to  bind to the
 118                                 LDAP server as, for online migration. This
 119                                 is optional; you'll be prompted if the
 120                                 environment variable is not set.
 121
 122  LDAP_BINDCRED                  The  password to  bind to   the LDAP server
 123                                 with, for online migration.  This is
 124                                 optional; you'll be prompted if the
 125                                 environment variable is not set.
 126
 127 You will  probably wish to use  a shell script or  makefile to automate
 128 population of your LDAP database, either off-lien (with ldif2ldbm) or
 129 on-line (with ldapadd). The migrate_all_*.sh shell scripts do this, but you
 130 may wish to customize their behaviour. The following table explains which
 131 migration scripts to use:
 132
 133  Shell script                     Existing nameservice    LDAP
 134                                                           running?
 135
 136  migrate_all_online.sh            /etc flat files         Yes
 137
 138  migrate_all_offline.sh           /etc flat files         No
 139
 140  migrate_all_netinfo_online.sh    NetInfo                 Yes
 141
 142  migrate_all_netinfo_offline.sh   NetInfo                 No
 143
 144  migrate_all_nis_online.sh        NIS/YP                  Yes
 145
 146  migrate_all_nis_offline.sh       NIS/YP                  No
 147
 148 Below are examples of  migrate_hosts.pl and migrate_passwd.plbeing used to
 149 migrate hosts and users, respectively:
 150
 151 $ migrate_hosts.pl /etc/hosts
 152 dn: cn=mira.aceindustry.com,ou=devices,dc=aceindustry,dc=com
 153 objectclass: ipHost
 154 objectclass: device
 155 objectclass: top
 156 ipHostNumber: 10.1.70.5
 157 cn: mira
 158 cn: www.aceindustry.com
 159 cn: mira.aceindustry.com
 160
 161 $ migrate_passwd.pl /etc/passwd
 162 dn: cn=Joe Bloggs,ou=people,dc=aceindustry,dc=com
 163 cn: Joe Bloggs
 164 objectclass: top
 165 objectclass: person
 166 objectclass: organizationalPerson
 167 objectclass: inetOrgPerson
 168 objectclass: posixAccount
 169 objectclass: account
 170 mail: jbloggs@aceindustry.com
 171 givenname: Joe
 172 sn: Bloggs
 173 uid: jbloggs
 174 userPassword: {crypt}daCXgaxahRNkg
 175 loginShell: /bin/csh
 176 uidNumber: 20
 177 gidNumber: 20
 178 homeDirectory: /home/jbloggs
 179