This appendix provides some general information about creating LDAP Data Interchange Files (LDIF) that can be used by the Oracle Internet Directory command-line tools. LDIF files are specially formatted text files that can be used to exchange data between LDAP directory servers, such as Oracle Internet Directory.
This appendix contains the following topics:
LDIF formats are defined by the Internet Engineering Task Force (IETF) in RFC 2849. Visit the IETF Web site at http://www.ietf.org/rfc/rfc2849.txt for more information about LDIF formatting rules. This section explains some general rules for formatting LDIF files.
Each line in an LDIF file must be correctly formatted in order to be read by the Oracle Internet Directory command-line tools. White space and line breaks must be used carefully.
Each line in an LDIF file is terminated with a line feed, which is <LF> on UNIX or <CR><LF> on Windows. In LDIF you can have the following types of lines:
Directive Line - Any line that does not begin with either a SPACE or # (hash). A directive line specifies either some type of data in an entry or an operation to perform.
Continuation Line - A line that begins with a SPACE denotes that the characters following the space are part of the previous line.
Blank Line - Blank lines are used to separate entries and are typically created with the ENTER key.
Comment Line - A comment line begins with a # (hash). Comments are ignored by the Oracle Internet Directory command-line tools.
Separator Line - A line that starts with a - (dash) character is used to end an operation. It denotes that the next line begins a new operation directive.
Unnecessary space characters in the LDIF input file, such as a space at the end of an attribute value, will cause the LDAP operations to fail.
The sequence of entries in your LDIF file must follow the Directory Information Tree (DIT) from the top down. Parent entries should be listed before their children entries. Any attributes or object classes used in an entry must exist in the schema or be added to the schema before they can be used. Separate entries with a blank line.
Reference binary files, such as photographs, with the absolute address of the file proceeded by a / (forward slash).
The standard format for directory entries is as follows:
dn: distinguished_name changetype: add|delete|modify|modrdn|moddn attribute_type: attribute_value ... objectClass: object_class_value ...
The dn directive defines the distinguished name (DN) of an entry. It is assumed that all lines below a dn directive belong to that entry until you add a space in the LDIF file to denote a separate entry. The following example shows a dn directive line:
dn: cn=Mary Jones,ou=Sales,dc=company,dc=com
The changetype directive defines the operation you want to perform on the entry. The operations that you specify with the changetype directive are:
add - See "LDIF Format for Adding Entries" for syntax and examples.
delete - See "LDIF Format for Deleting Entries" for syntax and examples.
modify - "LDIF Format for Modifying Entries" for syntax and examples.
modrdn - See "LDIF Format for Modifying the RDN of an Entry" for syntax and examples.
moddn - See "LDIF Format for Modifying the DN of an Entry" for syntax and examples.
If changetype directive is omitted, then an add operation is assumed if using bulkload, ldapadd or ldapaddmt. A delete operation is assumed if using bulkdelete or ldapdelete. All other operations must specify a changetype: directive.
The attribute_type directive is used to specify an attribute type name and value pair. The entry will have an attribute_type directive for each attribute in the entry. For example, here is an attribute_type directive for the attribute type named cn where the value is Mary Smith.
cn: Mary Smith
The objectClass directive is used to specify the object class that is associated with the entry. If an entry uses multiple object classes, then it will have an objectClass directive for each object class used. For example, here are the object classes used to define a user entry.
objectClass: orclUserV2 objectClass: organizationalPerson objectClass: person objectClass: top
Note that if an object class has required attributes, you must supply a value for those attributes using attribute_type directives.
The following example shows a file entry for an employee. The first line contains the DN. The second line contains the changetype: add directive. The lines that follow begin with the name for an attribute type, followed by the value to be associated with that attribute. Note that the photo attribute value begins with a forward slash (\) to denote that it is a binary file reference. Use an empty line at the end of the entry as a separator.
dn: cn=Suzie Smith,ou=Server Technology,o=Acme, c=US
changetype: add
cn: Suzie Smith
cn: Suzie
sn: Smith
mail: ssmith@us.Acme.com
telephoneNumber: 69332
photo: \$ORACLE_INSTANCE/empdir/photog/ssmith.jpg
objectClass: organizationalPerson
objectClass: person
objectClass: top
When deleting an entry by using ldapmodify or ldapmodifymt, the LDIF file entry only needs the DN of the entry to be deleted and the changetype: delete directive. Use an empty line at the end of the entry as a separator.
dn: cn=Suzie Smith,ou=Server Technology,o=Acme, c=US changetype: delete
The ldapdelete command only needs a list of DNs. It does not require a changetype operator.
When modifying an entry, you must supply the DN of the entry followed by the changetype: modify directive. Next you must specify the attributes you want to modify using one of the following directives:
add: attribute_type - Specifies the name of an attribute type for which you want to add a value. The next line should then contain the attribute_type: value directive for the value you want to add. For example:
add: work-phone work-phone: 510/506-7000
delete: attribute_type - Specifies the name of an attribute type for which you want to delete the value. If the attribute is multi-valued, then you should also supply the attribute_type: value directive for the specific value you want to delete, otherwise all values for the attribute are deleted. For example:
delete: home-fax
replace: attribute_type - Specifies the name of an attribute type for which you want to replace the existing value with a new value. The next line should then contain the attribute_type: value directive for the value you want to replace. For example:
replace: home-phone home-phone: 415/697-8899
If the attribute is multi-valued then all the current values are replaced with one or more attributes following this directive. If only a single value of a multi-valued attribute needs to be replaced use delete then add.
If you are making several modifications to an entry, then, between each modification you enter, add a line that contains a hyphen (-) only. For example:
dn: cn=Barbara Fritchy,ou=Sales,o=Oracle,c=US changetype: modify add: work-phone work-phone: 650/506-7000 work-phone: 650/506-7001 - delete: home-fax - replace: home-phone home-phone: 415/697-8899
To modify the relative distinguished name (RDN) for an entry, you must supply the DN of the entry followed by the changetype: modrdn directive. Next you must specify the new RDN with a newrdn: directive, and you can optionally delete or keep the old entry by supplying a deleteoldrdn: directive. For example:
dn: cn=Sally Smith,ou=people,dc=example,dc=com changetype: modrdn newrdn: dn=Sally Smith-Jones # deletes old RDN entry deleteoldrdn: 1
To modify the DN for an entry (move the entry to a new node in the DIT), you must supply the DN of the entry followed by the changetype: moddn directive. You must also specify the new parent DN with a newsuperior: directive, and you can optionally delete or keep the old entry by supplying a deleteoldrdn: directive. For example:
dn: cn=Sally Smith,ou=people,dc=example,dc=com changetype: moddn # keeps old RDN entry deleteoldrdn: 0 newsuperior: ou=expeople,dc=example,dc=com
Attribute types and object classes must be added to the Oracle Internet Directory schema before they can be used in entries.
Example: Adding an Attribute to the Schema
This example adds a new attribute to the schema called myAttr. The LDIF file for this operation is:
dn: cn=subschemasubentry changetype: modify add: attributetypes attributetypes: ( 1.2.3.4.5.6.7 NAME 'myAttr' DESC 'New attribute definition' EQUALITY caseIgnoreMatch SYNTAX '1.3.6.1.4.1.1466.115.121.1.15' )
On the first line, enter the DN specifying where this new attribute is to be located. All attributes and object classes are stored in cn=subschemasubentry.
The second and third lines show the proper format for adding a new attribute.
The last line is the attribute definition itself. The first part of this is the object identifier number: 1.2.3.4.5.6.7. It must be unique among all other object classes and attributes. Next is the NAME of the attribute. In this case the attribute NAME is myAttr. It must be surrounded by single quotes. Next is a description of the attribute. Enter whatever description you want between single quotes. At the end of this attribute definition in this example are optional formatting rules to the attribute. In this case we are adding a matching rule of EQUALITY caseIgnoreMatch and a SYNTAX of 1.3.6.1.4.1.1466.115.121.1.15 (which is the object ID for the syntax of "Directory String").
When you define schema within an LDIF file, insert a white space between the opening parenthesis and the beginning of the text, and between the end of the text and the ending parenthesis.
Example: Adding an Object Class to the Schema
Before you add the object class, all of the attribute types that the object class uses must be in the schema. If there are new attribute types, then define those first in your LDIF file before defining your object class.
The following example adds a new object class named myObjectClass to the schema.
dn: cn=subschemasubentry changetype: modify add: objectClasses objectClasses: ( 1.2.3.4.56789.1.0.200 NAME 'myObjectClass' SUP ( top ) STRUCTURAL MUST ( cn ) MAY ( myAttr1 $ myAttr2 $ myAttr3 ) )
On the first line, enter the DN specifying where this new object class is to be located. All attributes and object classes are stored in cn=subschemasubentry.
The second and third lines show the proper format for adding a new object class.
The last line is the object class definition itself. The first part of this is the object identifier number: 1.2.3.4.56789.1.0.200. It must be unique among all other object classes and attributes. Next is the NAME of the object class. In this case the object class name is myObjectClass. It must be surrounded by single quotes. Next is the superior (SUP) object classes, which in this case is top. STRUCTURAL denotes the type of object class. MUST and MAY denote the required and allowed attributes. Separate attribute names with a dollar sign ($).
When you define schema within an LDIF file, insert a white space between the opening parenthesis and the beginning of the text, and between the end of the text and the ending parenthesis. If using line breaks for formatting long lines, make sure to add a space at the beginning of a line to denote that it is a continuation of the previous line.
Example: Adding A New Object Class to an Entry
Before you can use a new object class and the attributes it contains, you must update the entry to use the new object class. The following example shows how to add a new object class to an entry. Note that you must define a value for all of the required attributes of the object class.
# Add a new AUXILIARY object class to an existing entry dn: cn=Robert Smith,ou=people,dc=example,dc=com changetype: modify # the object class used for binding objectclass: inetorgperson # objectclass being added objectclass: myObjectClass # MUST attributes of new object class myAttr1: some value myAttr2: my value myAttr3: a value
This section describes how to properly format an LDIF file for use with the Oracle Internet Directory Migration Tool. The migration tool enables you to take LDIF entries output from other directories or applications and covert the data to use the attributes and values found in Oracle Internet Directory entries. You do this by inserting substitution variables for the data elements you want to convert.
See "ldifmigrator" for more information about the Oracle Internet Directory Migration Tool.
Substitution variables are denoted in the LDIF file by the following syntax:
%s_variableName%
For example, let's say you have the following LDIF formatted entry that was exported from another application. The subtree where user entries are stored, the user nickname attribute, and the name of the user's organization are different in Oracle Internet Directory than in the original application. For those elements you want to convert, you would add substitution variables to the file as placeholders.
dn: cn=jdoe, %s_UserContainerDN%
sn: Doe
%s_UserNicknameAttribute%: jdoe
objectClass: inetOrgPerson
objectClass: orclUserV2
title: Member of Technical Staff
homePhone: 415-584-5670
homePostalAddress: 234 Lez Drive$ Redwood City$ CA$ 94402
ou: %s_UserOrganization%
When you run the Oracle Internet Directory Migration Tool against this file, it will find the variables and either replace then with the values you define on the command-line or look up the correct values in Oracle Internet Directory.
The Oracle Internet Directory Migration Tool recognizes several predefined substitution variables. If running the tool in lookup mode, the values for these variables can be looked up in Oracle Internet Directory. You can use these predefined variables or define variables of your own using the %s_variableName% syntax.
Table A-1 Predefined Substitution Variables
| Variable Name | Meaning | How OID Migration Tool Determines the Value for This Variable |
|---|---|---|
|
%s_UserContainerDN% |
Distinguished name of the entry under which all users are supposed to be added. |
This is assigned the value of the attribute: |
|
%s_GroupContainerDN% |
Distinguished name of the entry under which all public groups are supposed to be added. |
This is assigned the value of the attribute: |
|
%s_UserNicknameAttribute% |
The nickname attribute to be used for user entries in the identity management realm. |
This is assigned the value of the attribute: |
|
%s_SubscriberDN% |
Distinguished name of the LDAP entry corresponding to the identity management realm. |
If a simple subscriber name is given, the migration tool will resolve it to a DN using the attribute |
|
%s_SubscriberOracleContextDN% |
Distinguished name of the realm-specific Oracle Context. |
First the realm DN is computed as described earlier and then the string |
|
%s_RootOracleContextDN% |
Distinguished name of the Root Oracle Context. |
This is currently hard-coded to |
|
%s_CurrentUserDN% |
Distinguished name of the User who is loading the LDIF file. This is sometimes required to bootstrap the creation of groups which require at least one member in them. |
The migration tool expects this DN to be specified on the command line as part of the authentication information. |
When migrating entries into Oracle Internet Directory from another application, it is possible that there may be conflicts. For example, a user entry may already be defined in Oracle Internet Directory, or have conflicting values with the migrated data. In this case, the reconcile option will control what LDIF changetype directives are performed. There are three modes for reconciliation of migrated data:
SAFE - This mode only adds new entries that don't exist or appends new attributes to existing entries. If any other directive besides the following are specified in the LDIF file, they will not be applied.
changetype:add
changetype:modify
add: attribute_name (adds attribute only if it doesn't exist)
SAFE-EXTENDED - This mode only adds new entries that don't exist or appends new attributes to existing entries. If you try to add a new value for existing attributes, then it will add it to the existing set of values. If any other directive besides the following are specified in the LDIF file, they will not be applied.
changetype:add
changetype:modify
add: attribute_name (appends values if attribute exists)
NORMAL - This mode applies all directives as intended. The following directives are supported:
changetype:add
changetype:delete
changetype:modify add: attribute_name
replace: attribute_name
delete: attribute_name