[packages/MigrationTools.git] / MigrationTools.txt

LDAP Migration Tools

The MigrationTools are a set of Perl scripts for migrating users, groups,
aliases, hosts, netgroups, networks, protocols, RPCs, and services from
existing nameservices (flat files, NIS, and NetInfo) to LDAP. They are
located on a default installation under /usr/share/openldap/migration.

The tools require the ldapadd and ldif2dbm commands, which are distributed
with most LDAP servers derived from the University of Michigan LDAP
distribution. The source code for these is available with OpenLDAP.
Additionally, Netscape provide an implementation of ldapmodify which
subsumes the functionality of ldapadd. If you are using Netscape's Directory
Server, you should set the $NSHOME and $serverId environment variables to
assist the MigrationTools in locating your LDAP database and LDIF tools;
they will use ldapmodify instead of ldapadd.

These tools are freely redistributable according to the license included
with the source files. They may be bundled with LDAP/NIS migration products.
See RFC 2307 for more information on the schema used by these scripts. THIS
SOFTWARE IS PROVIDED "AS IS" WITHOUT EXPRESS OR IMPLIED WARRANTY AND WITHOUT
SUPPORT.

Scripts

   * migrate_base.pl creates naming context entries, including
     subordinate contexts such  as ou=people and ou=devices.
   * migrate_aliases.pl migrates aliases in /etc/aliases to entries
     conforming to the rfc822MailGroup schema. Organizations who have
     deployed LDAP-based  messaging solutions, such as Netscape's
     Messaging Server, may wish to use a different  schema for
     representing mail aliases. Ypldapd does not use X.500 groups (such
     as  groupOfUniqueNames) for mail alias expansion because
     flattening an arbitrarily nested  group at runtime may be
     expensive. (It is possible to write a ypldapd plug-in to support
     such a schema, however.)
   * migrate_group.pl migrates groups in /etc/group
   * migrate_hosts.pl migrates hosts in /etc/hosts
   * migrate_networks.pl migrates networks in /etc/networks
   * migrate_passwd.pl migrates users in /etc/passwd. Note that if
     users are  allowed read the userPassword attribute, and your LDAP
     server doesn't support  authenticating against hashed passwords
     then anyone may read the userPassword  attribute's value and
     authenticate as that user. Modern LDAP servers, such as  Netscape
     Directory Server, support authenticating against hashed passwords,
     so this is not  an issue. The OpenLDAP LDAP server also supports
     such authentication.
   * migrate_protocols.pl migrates protocols in /etc/protocols
   * migrate_services.pl migrates services in /etc/services
   * migrate_netgroup.pl migrates netgroups in /etc/netgroup
   * migrate_netgroup_byuser.pl migrates the netgroup.byuser map. It
     requires revnetgroup.
   * migrate_netgroup_byhost.pl migrates the netgroup.byhost map. It
     requires revnetgroup.
   * migrate_rpc.pl migrates RPCs in /etc/rpc

Configuration

The configuration  for these Perl scripts  is contained at the  head of
migrate_common.ph:

 Perl variable                  Description

 $DEFAULT_MAIL_DOMAIN           The mail  domain used for   the mail
                                attribute in  migrate_passwd.pl when
                                extended schema support is enabled.  You may
                                override this with the DEFAULT_MAIL_DOMAIN
                                environment variable.

 $DEFAULT_BASE                  The   naming  suffix   to  use    in
                                entries'  distinguished   names.  If
                                undefined, this will be constructed by
                                mapping the mail domain name into a
                                distinguished name (eg aceindustry.com
                                becomes dc=aceindustry,dc=com ).  You may
                                override this with the LDAP_BASEDN
                                environment variable.

 $EXTENDED_SCHEMA               Enables  extended  schema   support.
                                This  adds the  organizationalPerson and
                                inetOrgPerson object classes, amongst
                                others, to users migrated by the
                                migrate_passwd.pl script.

 NAMINGCONTEXT                  Determines  the   LDAP/X.500  naming context
                                to use for a migration tool.  The dictionary
                                is keyed by tool (as in migrate_ tool .pl ).
                                Values are concatenated with $DEFAULT_BASE
                                by the & getsuffix() subroutine.

The  following  environment  variables  control  the  behavior  of  the
migration shell scripts:

 Environment variable           Description

 DEFAULT_MAIL_DOMAIN            See above

 LDAPADD                        Path  the   ldapadd executable,  for online
                                migration (if not in the path or
                                /usr/local/bin or /usr/bin)

 LDIF2LDBM                      Path the  ldif2ldbm  executable, for offline
                                migration (if not in the path or
                                /usr/local/bin or /usr/bin)

 PERL                           Path  to the  Perl  interpreter  (if not
                                /usr/bin or /usr/local/bin)

 LDAPHOST                       Your   LDAP   server,  for    online
                                migration. This is optional; you'll be
                                prompted if the environment variable is not
                                set.

 LDAP_BASEDN                    See above ( $DEFAULT_BASE).  This is
                                optional; you'll be prompted if the
                                environment variable is not set.

 LDAP_BINDDN                    The distinguished  name  to  bind to the
                                LDAP server as, for online migration. This
                                is optional; you'll be prompted if the
                                environment variable is not set.

 LDAP_BINDCRED                  The  password to  bind to   the LDAP server
                                with, for online migration.  This is
                                optional; you'll be prompted if the
                                environment variable is not set.

You will  probably wish to use  a shell script or  makefile to automate
population of your LDAP database, either off-lien (with ldif2ldbm) or
on-line (with ldapadd). The migrate_all_*.sh shell scripts do this, but you
may wish to customize their behaviour. The following table explains which
migration scripts to use:

 Shell script                     Existing nameservice    LDAP
                                                          running?

 migrate_all_online.sh            /etc flat files         Yes

 migrate_all_offline.sh           /etc flat files         No

 migrate_all_netinfo_online.sh    NetInfo                 Yes

 migrate_all_netinfo_offline.sh   NetInfo                 No

 migrate_all_nis_online.sh        NIS/YP                  Yes

 migrate_all_nis_offline.sh       NIS/YP                  No

Below are examples of  migrate_hosts.pl and migrate_passwd.plbeing used to
migrate hosts and users, respectively:

$ migrate_hosts.pl /etc/hosts
dn: cn=mira.aceindustry.com,ou=devices,dc=aceindustry,dc=com
objectclass: ipHost
objectclass: device
objectclass: top
ipHostNumber: 10.1.70.5
cn: mira
cn: www.aceindustry.com
cn: mira.aceindustry.com

$ migrate_passwd.pl /etc/passwd
dn: cn=Joe Bloggs,ou=people,dc=aceindustry,dc=com
cn: Joe Bloggs
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
objectclass: posixAccount
objectclass: account
mail: jbloggs@aceindustry.com
givenname: Joe
sn: Bloggs
uid: jbloggs
userPassword: {crypt}daCXgaxahRNkg
loginShell: /bin/csh
uidNumber: 20
gidNumber: 20
homeDirectory: /home/jbloggs
Commit	Line	Data
5988af78	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