| Skip Navigation Links | |
| Exit Print View | |
|
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Oracle Fusion Middleware Administration Guide for Oracle Unified Directory 11g Release 1 (11.1.1) |
1. Starting and Stopping the Server
2. Configuring the Server Instance
3. Configuring the Proxy Components
4. Configuring Security Between Clients and Servers
5. Configuring Security Between the Proxy and the Data Source
6. Managing Oracle Unified Directory With Oracle Directory Services Manager
Populating a Stand-Alone Directory Server With Data
Importing Data Using import-ldif
To Import Data in Offline Mode
To Replace Existing Data During an Offline Import
To Append Imported Data to Existing Data
To Import Fractional Files by Using Filters
To Include or Exclude Attributes During Import
To Import a Compressed LDIF File
To Record Rejected or Skipped Entries During Import
To Import Data From a MakeLDIF Template
To Run an Import in Online Mode
Exporting Data Using export-ldif
To Export Part of a Back End by Using Filters
To Include or Exclude Attributes During Export
To Export to LDIF and Then Compress the File
To Run an Export in Online Mode
Creating MakeLDIF Template Files
Tuning the JVM and Java Arguments
Overview of the Backup and Restore Process
To Back Up All Back Ends with Encryption and Signed Hashes
To Perform an Incremental Backup on All Back Ends
To Back Up a Specific Back End
To Perform an Incremental Backup on a Specific Back End
To Schedule a Backup as a Task
Backing Up the Server Configuration
Backing Up for Disaster Recovery
To Back Up the Directory Server For Disaster Recovery
Backing up and Restoring Data Using File System Snapshots
To Take a ZFS Snapshot On a Dedicated Backup Server
To Restore a Directory Server From a ZFS Snapshot
To Restore a Back End From Incremental Backups
To Schedule a Restore as a Task
To Restore the Configuration File
To Restore a Directory Server During Disaster Recovery
Restoring Replicated Directory Servers
Overview of the ldapsearch Command
ldapsearch Location and Format
Specifying Filter Types and Operators
Using UTF-8 Encoding in Search Filters
Using Special Characters in Search Filters
To Search for Specific User Attributes
To Perform a Search With Base Scope
To Perform a Search With One-Level Scope
To Perform a Search With Subtree Scope
To Return Attribute Names Only
To Return User Attributes Only
To Search For Specific Object Classes
To Return a Count of All Entries in the Directory
To Perform a Search With a Compound Filter
To Perform a Search Using a Filter File
To Limit the Number of Entries Returned in a Search
Searching Data With Oracle Directory Services Manager
Using Advanced Search Features
Searching for Special Entries and Attributes
To Search for Operational Attributes
To Search the Configuration Entry
To Search the Monitoring Entry
To Search Over SSL With Blind Trust
To Search Over SSL Using a Trust Store
To Search Over SSL With No Trust Store
To Search Over SSL Using a Keystore
To Search Using SASL With DIGEST-MD5 Client Authentication
To Search Using SASL With the GSSAPI Mechanism
To Search Using SASL With the PLAIN Mechanism
To View the Available Controls
To Search Using the Account Usability Request Control
To Search Using the Authorization Identity Request Control
To Search Using the Get Effective Rights Control
To Search Using the LDAP Assertion Control
To Search Using the LDAP Subentry Control
To Search Using the Manage DSA IT Control
To Search Using the Matched Values Filter Control
To Search Using the Password Policy Control
To Search Using the Persistent Search Control
To Search Using the Proxied Authorization Control
To Search Using the Server-Side Sort Control
To Search Using the Simple Paged Results Control
Searching Using the Virtual List View Control
To Search Using the Virtual List View Control
To Search Using Virtual List View With a Specific Target
To Search Using Virtual List View With a Known Total
Searching in Verbose Mode and With a Properties File
To Search Using a Properties File
Searching Internationalized Entries
Adding, Modifying, and Deleting Directory Data
To Add an Entry Using the --defaultAdd Option With ldapmodify
To Add Entries Using an LDIF Update Statement With ldapmodify
To Add an Attribute to an Entry
To Add an International Attribute
To Modify an Attribute With Before and After Snapshots
To Delete an Entry With ldapmodify
To Delete an Entry With ldapdelete
To Delete Multiple Entries by Using a DN File
Configuring Indexes on the Local DB Back End
To Create a New Local DB Index
To Enable or Disable Compact Encoding
To Enable or Disable Entry Compression
Ensuring Attribute Value Uniqueness
Overview of the Unique Attribute Plug-In
Configuring the Unique Attribute Plug-In Using dsconfig
To Ensure Uniqueness of the Value of the uid Attribute
To Ensure Uniqueness of the Value of Any Other Attribute
Replication and the Unique Attribute Plug-In
Configuring Virtual Attributes
To List the Existing Virtual Attributes
To Create a New Virtual Attribute
To Enable or Disable a Virtual Attribute
To Display the Configuration of a Virtual Attribute
To Change the Configuration of a Virtual Attribute
Extensions to the Collective Attributes Standard
Collective Attributes and Conflict Resolution
Excluding Collective Attributes From Specific Entries
Configuring Collective Attributes
To Create a New Collective Attribute
To Delete a Collective Attribute
To List the Collective Attributes That Apply to an Entry
Inherited Collective Attributes
Specifying Inherited Collective Attributes
Managing Data With Oracle Directory Services Manager
View the Attributes of an Entry
Add an Entry Based on an Existing Entry
Delete an Entry and its Subtree
10. Managing Users and Groups With dsconfig
11. Managing Password Policies
The directory server provides several mechanisms to move data into and out of a specific back end. This chapter outlines the various options and then describes the import and export mechanisms in more detail.
This section covers the following topics:
To populate a stand-alone directory server with data, use one of the following methods:
Import the data from an LDAP Data Interchange Format (LDIF) file while you are setting up the server, either by using the setup utility in GUI mode or by using the setup utility in interactive command-line mode. This is the most convenient method of initializing a stand-alone server or the first server in a replicated topology.
Start with an empty suffix and add entries by using the ldapmodify command, for example:
$ ldapmodify -h localhost -p 1389 -D "cn=Directory Manager" -w password \ -a -f /usr/local/add_entry.ldif
Import data from an LDIF file, using the import-ldif command. For example:
$ import-ldif -b dc=example,dc=com -n userRoot -l /var/tmp/Example.ldif
This method is much more efficient for the addition of bulk entries. The import-ldif command imports data from an LDIF file either by replacing any existing data in the suffix or by appending data to a base DN. Similarly, the export-ldif command exports entries from a database to an LDIF file, which can then be imported to another server. Both tools support file compression, SASL extension, and client/server authentication using SSL and startTLS.
Copy the binary database from another server. This method is also called binary copy.
$ cp instance-path/db/example.db destination-path/db
Restore the database from a backup using the restore command, for example:
$ restore -d /home/backup/userRoot
Note - Performing a binary database copy or restoring a database from a backup requires the source server and the destination server to have the same database remote LDAP structures and indexes.
The import-ldif command is used to populate a directory server back end with data read from an LDIF file or with data generated based on a Creating MakeLDIF Template Files. In most cases, import-ldif is significantly faster than adding entries using ldapmodify.
The import-ldif command supports both LDIF files and compressed files (.zip).
Note -
A complete import to an entire Oracle Berkeley DB Java Edition (JE) back end will have better performance than a partial import to a branch of the JE back end. All imported LDIF files must use UTF-8 character-set encoding.
Importing suffixes is a resource-intensive operation. If you import LDIF files that include a large number of suffixes, your system might have insufficient heap to complete the import operation. Before importing such LDIF files, you should therefore increase the heap as much as possible. For more information, see Chapter 14, Tuning Performance and Importing Large Data Sets.
You do not need root privileges to import an LDIF file, but you must authenticate as a user with root permissions, such as cn=Directory Manager.
The import-ldif command has two modes of operation: online and offline.
Online mode. In online mode, import-ldif contacts a running directory server instance and registers an import task. The command accesses the task back end over SSL via the administration connector. For more information, see Managing Administration Traffic to the Server. Online mode runs automatically when any connection options (such as --hostname, --port, --bindDN, and --bindPassword) are specified.
In general, if you expect to do online imports, you should increase the heap when you start the server. For more information, see Chapter 14, Tuning Performance.
Offline mode. When no connection options are specified, the command runs in offline mode. In offline mode, import-ldif accesses the database directly rather than through a directory server instance. In this case, the directory server must be stopped.
This procedure imports a remote LDAP database with new entries specified in an import LDIF file. The command runs in offline mode, which requires the server to be shut down prior to import.
$ stop-ds
$ import-ldif -b dc=example,dc=com -n userRoot -l Example.ldif
This command specifies the base DN for the branch of the data that should be included in the import (-b), the back-end ID into which the data is imported (-n), and the LDIF file used for the import (-l).
The following procedure replaces an existing back-end with new entries specified in an import file.
$ stop-ds
$ import-ldif --includeBranch dc=example,dc=com --backendID userRoot \ --replaceExisting --ldifFile Example.ldif
The following procedure appends the entries in an import file to the existing entries in the back end.
$ stop-ds
$ import-ldif --backendID userRoot --append --ldifFile new.ldif
The import-ldif command provides options to import a portion of an import file by specifying the base DN to include or exclude during the process.
This example imports all entries below the base DN, dc=example,dc=com, and excludes all entries below ou=People,dc=example,dc=com.
$ stop-ds
$ import-ldif --includeBranch dc=example,dc=com \ --excludeBranch ou=People,dc=example,dc=com --backendID userRoot --replaceExisting \ --ldifFile Example.ldif
The import-ldif command provides options to import part of an import file by using filters for data inclusion or exclusion. Make sure that you fully understand how this mechanism works before you use it.
In this example, the contents of an LDIF file are imported, except those entries that match the search filter l=Auckland (that is, location=Auckland).
Note - The --includeFilter option works in a similar manner to --excludeFilter, except that it includes all entries that match the search filter during import.
$ stop-ds
$ import-ldif --excludeFilter "(l=Auckland)" --backendID userRoot \ --replaceExisting --ldifFile Example.ldif
The import-ldif command provides options to include and exclude attributes during import by using the --includeAttribute and --excludeAttribute options, respectively. Make sure that you fully understand how this mechanism works before you use it.
$ stop-ds
The directory server provides useful utilities to search, modify, compare, or delete import files without connecting to the server. You can use the ldifsearch command to display an entry in your import file. For example, to display the entry for Sam Carter, use the following command:
$ ldifsearch -b dc=example,dc=com --ldifFile Example.ldif "(cn=Sam Carter)" dn: uid=scarter,ou=People,dc=example,dc=com objectClass: person objectClass: inetOrgPerson objectClass: organizationalPerson objectClass: top givenname: Sam uid: scarter cn: Sam Carter telephonenumber: +1 408 555 4798 sn: Carter userpassword: sprain roomnumber: 4612 mail: scarter@example.com l: Sunnyvale ou: Accounting ou: People facsimiletelephonenumber: +1 408 555 9751
In this entry, notice the presence of the roomnumber attribute below the telephonenumber attribute.
$ import-ldif --excludeAttribute "roomnumber" --backendID userRoot \ --replaceExisting --ldifFile Example.ldif
$ start-ds
The following example shows that the roomnumber attribute is now absent from Sam Carter's entry.
$ ldapsearch --port 1389 --baseDN dc=example,dc=com --bindDN "cn=Directory Manager" \ --bindPassword password "(cn=Sam Carter)" dn: uid=scarter,ou=People,dc=example,dc=com \ objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: top givenName: Sam uid: scarter cn: Sam Carter sn: Carter telephoneNumber: +1 408 555 4798 ou: Accounting ou: People l: Sunnyvale mail: scarter@example.com facsimileTelephoneNumber: +1 408 555 9751
The import-ldif utility supports compressed LDIF files.
$ stop-ds
$ import-ldif --includeBranch dc=example,dc=com --excludeBranch "ou=People,dc=example,dc=com" --ldifFile Example.ldif \ --backendID userRoot --replaceExisting --isCompressed
The import-ldif command provides a means to write to an output file for any entries that are rejected or skipped during the import process. This enables easy debugging of an LDIF file. Rejected entries occur when the directory server rejects the added entries due to schema violations. Skipped entries occur when entries cannot be placed under the specified base DN.
$ stop-ds
You can also use the --overWrite option to replace any previous items in the two files. Without the option, the directory server appends new rejected and skipped entries to the existing files.
$ import-ldif --backendID userRoot --append --ldifFile new.ldif --overwrite --rejectFile rejected.ldif --skipFile skipped.ldif
$ more rejected.ldif # Entry ou=Contractors,dc=example,dc=com read from LDIF starting at line 1 is not valid because it violates the server's schema configuration: Entry ou=Contractors,dc=example,dc=com violates the Directory Server schema configuration because it includes attribute changeType which is not allowed. changetype: add objectclasses defined in that entry objectclass: top objectclass: organizationalUnit ou: Contractors ou: Product Testing ou: Product Dev ou: Accounting ... $ more skipped.ldif # Skipping entry ou=People,dc=example,dc=com because the DN is not one that should be included based on the include and exclude branches objectclass: top objectclass: organizationalunit ou: People aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr ="userpassword || telephonenumber || facsimiletelephonenumber")(version 3.0;acl "Allow self entry modification"; allow (write)(userdn = "ldap:///self");) aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || uid") (targetfilter ="(ou=Accounting)")(version 3.0;acl "Accounting Managers Group Permissions"; allow (write) (groupdn = "ldap:///cn=Accounting Managers,ou=groups,dc=example,dc=com");) aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || uid") (targetfilter ="(ou=Human Resources)")(version 3.0;acl "HR Group Permissions"; allow write)(groupdn = "ldap:///cn=HR Managers,ou=groups,dc=example,dc=com");) aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn ||sn || uid") (targetfilter ="(ou=Product Testing)")(version 3.0;acl "QA Group Permissions"; allow (write)(groupdn = "ldap:///cn=QA Managers,ou=groups,dc=example,dc=com");) aci: (target ="ldap:///ou=People,dc=example,dc=com")(targetattr h3.="cn || sn || uid") (targetfilter ="(ou=Product Development)")(version 3.0;acl "Engineering Group Permissions"; allow (write)(groupdn = "ldap:///cn=PD Managers,ou=groups,dc=example,dc=com");) ...
The directory server includes the Java utility, makeLDIF, that can be used to generate sample data for import. The makeLDIF utility requires a template file. You can create your own template file, or you can use the template file located in install-dir/config/MakeLDIF/example.template, editing it as required. For more information, see Creating MakeLDIF Template Files.
$ stop-ds
The sample template generates 10,003 sample entries in the specified back end.
$ import-ldif --backendID userRoot --templateFile example.template --randomSeed 0
make-ldif in Oracle Fusion Middleware Command-Line Usage Guide for Oracle Unified Directory
The import-ldif utility can also be run with the server online. In online mode, the command accesses the task back end over SSL via the administration connector. To run the command in online mode you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates. For more information, see Managing Administration Traffic to the Server.
$ import-ldif -h localhost -port 4444 -D "cn=Directory Manager" -w password -X \ -l /ldif-files/example.ldif
The import-ldif utility provides a --start option for scheduling the import at some future date. You can view this scheduled task by using the manage-tasks utility. The command accesses the task back end over SSL via the administration connector. To schedule an import task, you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates. For more information, see
$ import-ldif -h localhost -port 4444 -D "cn=Directory Manager" -w password -X \ -l /ldif-files/example.ldif --start 20080124121500
The export-ldif command is used to export data from a directory server back end. The command is useful for the following tasks:
Backing up directory data
Exporting data to another application
Repopulating a database after a change to the directory topology
Reinitializing master servers in a replicated topology
Note - The export-ldif command cannot be used to export data from the following back ends: monitor, ads-truststore, backup, and config-file-handler.
The export-ldif command has two modes of operation: online and offline.
Online mode. In online mode, export-ldif contacts a running directory server instance and registers an export task. This mode runs automatically when the LDAP connection options (--hostname, --port, --bindDN, and --bindPassword) are used. The command accesses the task back end over SSL via the administration connector. For more information, see Managing Administration Traffic to the Server.
Offline mode. When no connection options are specified, the command runs in offline mode. In offline mode, export-ldif accesses the database directly rather than through a directory server instance. In this case, the directory server must be stopped.
$ stop-ds
$ export-ldif --includeBranch "dc=example,dc=com" --backendID userRoot \ --ldifFile example.ldif
The export-ldif command provides options to export a part of a back end by specifying the base DN and its children for inclusion or exclusion during processing.
$ stop-ds
In this example, only the entries under ou=People,dc=example,dc=com are exported.
$ export-ldif --includeBranch ou=People,dc=example,dc=com --backendID userRoot \ --ldifFile example-people.ldif
The ldifsearch command verifies entries in an LDIF file without connecting to the directory server. You can use it in a manner similar to the ldapsearch command. For example:
$ ldifsearch -b dc=example,dc=com --ldifFile export.ldif "(objectclass=*)"
dn: ou=People,dc=example,dc=com
objectClass: organizationalunit
objectClass: top
ou: People
dn: uid=scarter,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: top
givenName: Sam
uid: scarter
cn: Sam Carter
sn: Carter
telephoneNumber: +1 408 555 4798
userPassword: {SSHA}Ocpp2P4sImz2MziL69AUG9+khdIhFpmU4B5mvA==
roomNumber: 4612
ou: Accounting
ou: People
l: Sunnyvale
mail: scarter@example.com
facsimileTelephoneNumber: +1 408 555 9751 ...The export-ldif command provides options to export part of a back end by using a search filter. The directory server includes or excludes all entries that match the filter. Make sure that you fully understand how this mechanism works before you use it.
In this example, only those entries that match the search filter l=Cupertino (that is, location=Cupertino) are exported. The --excludeFilter option works in a similar manner to --includeFilter, except that it excludes all entries that match the filter during export.
$ stop-ds
$ export-ldif --includeFilter "(l=Cupertino)" --backendID userRoot \ --ldifFile export.ldif
The export-ldif utility provides options to include and exclude attributes during export by using the --includeAttribute and --excludeAttribute options, respectively. Make sure that you fully understand how this mechanism works before you use it.
$ ldapsearch --baseDN dc=example,dc=com "(cn=Sam Carter)" dn: uid=scarter,ou=People,dc=example,dc=com objectClass: person objectClass: inetOrgPerson objectClass: organizationalPerson objectClass: top givenname: Sam uid: scarter cn: Sam Carter telephonenumber: +1 408 555 4798 sn: Carter userpassword: sprain roomnumber: 4612 mail: scarter@example.com l: Sunnyvale ou: Accounting ou: People facsimiletelephonenumber: +1 408 555 9751
$ stop-ds
You can use the --includeAttribute option multiple times for each attribute that should be included. In this example, only the top level attributes are exported.
$ export-ldif --backendID userRoot --includeAttribute dn --includeAttribute dc \ --includeAttibute cn --includeAttribute sn --includeAttribute givenname \ --includeAttribute objectclass --includeAttribute ou --includeAttribute uid \ --ldifFile export.ldif
If an error occurs, the server continues processing the command.
$ ldifsearch --baseDN dc=example,dc=com --ldifFile export.ldif "(objectclass=*)" dn: dc=example,dc=com objectClass: domain objectClass: top dc: example dn: ou=Groups,dc=example,dc=com objectClass: organizationalunit objectClass: top ou: Groups dn: cn=Directory Administrators,ou=Groups,dc=example,dc=com objectClass: groupofuniquenames objectClass: top cn: Directory Administrators ou: Groups dn: ou=People,dc=example,dc=com objectClass: organizationalunit objectClass: top ou: People ...
The export-ldif command allows you to compress the output LDIF file.
$ stop-ds
$ export-ldif --backendID userRoot --ldifFile export.ldif --compress
The export-ldif command can also be run with the server online. In online mode, the command accesses the task back end over SSL via the administration connector. For more information, see Managing Administration Traffic to the Server. To run the command in online mode you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates.
$ export-ldif -h localhost -p 4444 -D "cn=Directory Manager" -w password -X \ --includeBranch "dc=example,dc=com" --backendID userRoot --ldifFile export.ldif
The export-ldif utility provides a --start option for scheduling the export at some future date. You can view this scheduled task by using the manage-tasks utility. The command accesses the task back end over SSL via the administration connector. For more information, see Managing Administration Traffic to the Server. To schedule an export task, you must specify the relevant connection options, including how the SSL certificate will be trusted. This example uses the -X option to trust all certificates.
The server must be running to schedule an export.
The --start option takes as its value a date and time in the format yyyymmddhhmmss. For example:
$ export-ldif -h localhost -p 4444 -D "cn=Directory Manager" -w password -X \ --includeBranch "dc=example,dc=com" --backendID userRoot \ --ldifFile export.ldif --start 20080124121500
The make-ldif command can use template files to define the way in which LDIF files are to be generated. This approach allows for flexibility without the need to alter any code to produce the desired result. The topics in this section describe how to use the make-ldif command to create customized LDIF files.
Template files can contain up to four sections, that must be provided in the following order:
Custom tag includes provide a mechanism for loading custom tags and making them available for use when processing make-ldif templates. This should be done using the include directive, as follows:
include com.example.opends.makeldif.MyCustomTag
The specified class must be in the class path, and it must be a subclass of the org.opends.server.tools.makeldif.Tag class. For information about developing custom tags, see Defining Custom Tags.
All of the standard replacement tags that are provided with make-ldif are automatically available for use and therefore do not require an explicit include directive.
The first section that should be present in the template file is the section that defines the global replacement variables. Global replacement variables are used to define strings of text that can be referenced later in the template file and are automatically replaced as each line is read into memory (much like a C preprocessor replaces macros in code with their defined values). For example, the following replacement variable definition creates a global replacement variable named suffix with a value of dc=example,dc=com:
define suffix=dc=example,dc=com
When a global replacement variable is defined, any case in which that variable name appears in square brackets (for example, [suffix]), causes the token to be replaced with the value that has been defined for that replacement variable.
When all the replacement variable definitions have been read (as signified by the first blank line following one or more replacement variable definitions), all remaining lines that are read from the template file are processed on a line-by-line basis. Any occurrences of a replacement variable name in square brackets are replaced with the value of that variable. Because that replacement is done as the template file is read into memory, replacement variables can occur in any point, including branch and template definitions, and even inside tags.
If there are global replacement variables defined in the template file, they must appear at the top of the file and there should not be any spaces between them. However, replacement variables are not required. If there are no replacement variables, the template file must start with the branch definitions.
Branch definitions are used in make-ldif template files to define the basic structure to use for the generated LDIF. They specify the entry or entries that should appear at the top of the hierarchy, and the number and types of entries that should appear below them.
The most basic form of a branch definition is as follows:
branch: dc=example,dc=com
This example specifies that the following entry is to be created with a DN of dc=example,dc=com:
dn: dc=example,dc=com objectClass: top objectClass: domain dc: example
The basic structure of the entry is defined by the RDN attribute of dc specified in the DN of the branch definition. The make-ldif command automatically associates the dc RDN attribute with the domain object class. The make-ldif command has similar definitions for other common RDN attributes in branch entries:
Creates an entry with the organization object class.
Creates an entry with the organizationalUnit object class.
Creates an entry with the country object class.
You can also use any other kind of RDN attribute for a branch entry. For branch entries with an RDN attribute other than the ones specified above, the entry is created with the untypedObject and extensibleObject object classes.
The branch definition provided above does not cause any additional entries to be created below that branch entry. To do this, you must specify one or more subordinateTemplate lines. For example:
branch: ou=People,dc=example,dc=com subordinateTemplate: person:100
This causes the ou=People,dc=example,dc=com entry to be created, and then 1000 other entries created below it modeled after the person template. The person template should be defined later in the template file. For more information, see Template Definitions.
Note - Branch entries are not limited to just one subordinateTemplate definition. You can specify multiple subordinateTemplate definitions by including them on separate lines of the branch definition. The following example creates 1000 entries based on the person template and an additional 100 entries based on the certificatePerson template:
branch: ou=People,dc=example,dc=com subordinateTemplate: person:10000 subordinateTemplate: certificatePerson:100
In all of the examples described previously, the branch entries themselves contain only the DN, the RDN attribute, and the object classes associated with the RDN attribute. You can include any other attributes in the branch entry by including them in the branch definition in the template file. For example, the branch definition:
branch: dc=example,dc=com description: This is the description for dc=example,dc=com
creates the entry:
dn: dc=example,dc=com objectClass: top objectClass: domain dc: example description: This is the description for dc=example,dc=com
This additional text can be static, can contain any defined global replacement variables, or can contain a subset of the replacement tags that can be used in template definitions. For an overview of the tags available and information about which tags can be used in branch definitions, see Standard Replacement Tags.
The heart of the make-ldif template file structure is the set of template definitions. Templates define the structure of the entries that are generated. They specify the set of attributes that should be included in the entries and the types of values that those attributes should contain. The specification of values is handled through tags that are parsed by make-ldif and replaced with the appropriate values for those tags.
A sample template definition might look as follows:
template: person
rdnAttr: uid
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
initials: {givenName:1}<random:chars:ABCDEFGHIJKLMNOPQRSTUVWXYZ:1>{sn:1}
employeeNumber: <sequential:0>
uid: user.{employeeNumber}
mail: {uid}@[maildomain]
userPassword: password
telephoneNumber: <random:telephone>
homePhone: <random:telephone>
pager: <random:telephone>
mobile: <random:telephone>
street: <random:numeric:5> <file:streets> Street
l: <file:cities>
st: <file:states>
postalCode: <random:numeric:5>
postalAddress: {cn}${street}${l}, {st} {postalCode}
description: This is the description for {cn}.
This example illustrates some of the flexibility that make-ldif provides when generating LDIF data. The tags that can be included in a template definition are described in the topics that follow (see Standard Replacement Tags and Attribute Value Reference Tags).
At the top of the template definition are two lines that provide information about the template itself and are not included in the entries created from this template. The first line specifies the name of the template. This is the name that is referenced in the subordinateTemplate lines of the branch definition. The second line specifies the name of the attribute that should be used as the RDN attribute for the entry. The RDN attribute must be assigned a value in the body of the template definition, and the way in which the value is assigned must ensure that the value will be unique among all other entries created with the same template below the same parent.
Note - It is possible to specify multivalued RDNs by separating the attribute names with a plus sign, as shown in the following example:
rdnAttr: uid+employeeNumber
If multivalued RDNs are used, all of the RDN attributes must be defined values in the template body and the combination of the RDN values for each entry must be unique. However, it is possible for one or more of the attributes in the RDN to be non-unique as long as the combination is never duplicated.
In addition to the template and rdnAttr lines, you can include one or more subordinateTemplate lines. This enables you to include dynamically-generated entries below other entries that have been dynamically generated (for example, if each user entry has one or more entries below it), and to allow for complex hierarchies. Although there is no limit placed on this level of nesting, you must ensure that no recursive loops are created by having a subordinateTemplate that either directly or indirectly will create additional entries using the same template.
Template definitions also support the concept of inheritance through the use of the extends keyword. For example, entries generated from the following template definition include all of the attributes defined in the person template as well as userCertificate;binary with the specified format:
template: certificatePerson rdnAttr: uid extends: person userCertificate;binary:: <random:base64:1000>
Multiple inheritance is allowed (by including multiple lines with the extends keyword), but as with the subordinateTemplate keyword it is important not to create a recursive loop in which a template file could either directly or indirectly inherit from itself.
To ensure that make-ldif can generate LDIF files that can be used to simulate a wide variety of deployments, a large number of tags have been defined for use in templates. This section describes the standard set of tags that can be used in a make-ldif template file. You can also create custom tags, as described in Defining Custom Tags.
The make-ldif standard replacement tags are special elements that are enclosed in angle brackets (beginning with a less-than sign (<) and ending with a greater-than sign (>) that are dynamically replaced with generated values. Some standard replacement tags do not require any arguments (for example, <first>). Others do take arguments, in which case the tag name comes first followed by a colon and the argument list with a colon between each argument (for example, <random:numeric:5>). The tag name is treated in a case-insensitive manner, although the arguments are generally case sensitive.
The following types of standard replacement tags are currently included as part of make-ldif:
The DN standard replacement tag is replaced with the DN of the current entry. If that DN is not yet available (for example, because the RDN attribute has not yet been assigned a value in the entry being generated), it is replaced with an empty string. In general, you should ensure that all RDN attributes are assigned values earlier in the template before this tag is used.
The DN tag can be used without any arguments (for example, <DN>), in which case it is replaced with the full DN of the entry. The tag can also take a single integer argument, which specifies the maximum number of components to include in the output. For example, the tag <DN:1> will only include the left most DN component (often called the RDN) for the entry. So if the entry being generated will have a DN of uid=john.doe,ou=People,dc=example,dc=com, the tag <DN:1> will be replaced with uid=john.doe. If the argument value is negative rather than positive, then it takes the absolute value of the given argument value and takes that number of components from the end of the DN. For example, using a DN of uid=john.doe,ou=People,dc=example,dc=com the tag <DN:-1> is replaced with dc=com.
This tag can be used in both branch and template definitions.
The File standard replacement tag is replaced with a line from a specified file. It requires either one or two arguments. The first argument is the path to the data file, and can be either an absolute path or the name of a file (with no path information) that is contained in the config/MakeLDIF directory. If there is a second argument, it must have a value of either sequential or random, which indicates whether the lines in the file should be taken in sequential order or chosen at random. If the second argument is not provided, the values are selected at random. For example, the tags <file:cities> and <file:cities:random> both cause the tag to be replaced with a randomly-selected line from the cities file, but the tag <file:cities:sequential> causes the city names to be taken in sequential order. If sequential ordering is used and all values are exhausted, it will wrap back around to the first line of the file.
The make-ldif command includes a number of standard data files that can be used in generated data. These files are included in the config/MakeLDIF directory and therefore only the filename is required. The files include:
Contains a list of common city names
Contains a list of common first names
Contains a list of common last names
Contains a list of all two-character US state abbreviations
Contains a list of common street names
This tag can be used in both branch and template definitions.
The First standard replacement tag is replaced with a first name taken from the config/MakeLDIF/first.names file. Note that there is a special relationship between the <first> and <last> tags such that the combination of the first and last names is always unique. When every possible combination from the first and last name files has been exhausted, make-ldif appends an integer value onto the last name to ensure that the value always remains unique.
The <first> tag does not take any arguments. It can be used only in template definitions. It is not allowed for use in branch definitions.
The GUID standard replacement tag is replaced with a randomly generated GUID (globally-unique identifier) value. All GUID values generated are guaranteed to be unique. The values generated consist of 32 hexadecimal digits in dash-delimited groups of 8, 4, 4, 4, and 12 digits, respectively (for example, 12345678-90ab-cdef-1234-567890abcdef).
The <guid> tag does not take any arguments. It can be used in both branch and template definitions.
The IfAbsent standard replacement tag does not generate any value of its own, and is therefore always be replaced with an empty string. However, its value is that it can prevent an attribute from appearing in the entry altogether based on whether a specified attribute or attribute value exists.
For example, consider the following template:
template: example
rdnAttr: cn
objectClass: top
objectClass: untypedObject
objectClass: extensibleObject
cn: <guid>
displayName: <presence:50>{cn}
description: <ifabsent:displayName>{cn} In this case, the description attribute is only included in the generated entry if the displayName attribute is not included (that is, the resulting entry will contain either displayName or description but not both).
The IfAbsent tag requires either one or two arguments. The first argument is the name of the target attribute. If there is a second argument, it specifies a particular value for the target attribute. If a value is provided, the IfAbsent tag takes action if that value is included in the generated entry.
This tag can be used in both branch and template definitions.
The IfPresent standard replacement tag does not generate any value of its own, and is therefore always replaced with an empty string. However, its value is that it can prevent an attribute from appearing in the entry altogether based on whether a specified attribute or attribute value exists.
For example, consider the following template:
template: example
rdnAttr: cn
objectClass: top
objectClass: untypedObject
objectClass: extensibleObject
cn: <guid>
displayName: <presence:50>{cn}
description: <ifpresent:displayName>{cn} In this case, the description attribute will only be included in the generated entry if the displayName attribute is also included (that is, the resulting entry will either contain neither attribute or it will contain both attributes).
The IfPresent tag requires either one or two arguments. The first argument is the name of the target attribute. If there is a second argument, it specifies a particular value for the target attribute. If a value is provided, the IfPresent tag will only take action if that value is included in the generated entry.
This tag can be used in both branch and template definitions.
The Last standard replacement tag is replaced with a last name taken from the config/MakeLDIF/last.names file. Note that there is a special relationship between the <first>and <last>tags such that the combination of the first and last names will always be unique. When every possible combination from the first and last name file has been exhausted, make-ldif will append an integer value onto the last name to ensure that the value always remains unique.
The <last>tag does not take any arguments. It can only be used in template definitions. It is not allowed for use in branch definitions.
The List standard replacement tag is replaced with a string selected from a provided list of values. The values to use should be provided as arguments to the List tag (at least one argument must be provided). Optionally, each value can be followed with a semicolon and an integer value that specifies the relative weight for that value. If a value does not include a weight, the weight for that item is assumed to be one. The weight is used to control how frequently the associated value is chosen compared with all of the other values in the list.
For example, to select from a list of the colors red, green, and blue in which all listed colors have equal weights, you can use:
<list:red:green:blue>
If the color red is to appear twice as frequently as either of the other colors, you can use:
<list:red;2:green;1:blue;1>
Note that in this case, the ;1 following the green and blue elements are not technically needed since the weight of any item that does not explicitly include a weight is one, but it is provided in the example above for clarity.
This tag can be used in both branch and template definitions.
The ParentDN standard replacement tag is replaced with the DN of the parent entry of the entry being generated. This should always be available.
This tag does not take any arguments. It can only be used in template definitions. It cannot be used in branch definitions.
The Presence standard replacement tag does not generate any value of its own, and is therefore always replaced with an empty string. However, its value is that it can be used to cause the associated attribute to appear in the entry a specified percentage of the time.
For example, consider the following template:
template: example
rdnAttr: cn
objectClass: top
objectClass: untypedObject
objectClass: extensibleObject
cn: <guid>
displayName: <presence:50>{cn} In this case, the displayName attribute will only be present in about 50% of the entries generated.
The Presence tag requires exactly one argument, which is an integer value between 0 and 100, indicating the percentage of entries that should have the associated attribute.
This tag can be used in both branch and template definitions.
The Random standard replacement tag is replaced with a randomly-generated value. A number of different types of values can be generated. This tag accepts a variable number of arguments, but the first argument always specifies the type of value to generate. That type may be one of the following values:
This causes the tag to be replaced with a specified number of lowercase ASCII alphabetic characters (that is, the character set abcdefghijklmnopqrstuvwxyz). This requires exactly one more argument, which is an integer specifying the number of characters to include in the generated value. For example, <random:alpha:5> generates a string of five randomly-selected alphabetic characters.
This causes the tag to be replaced with one or more numeric digits. There can be either one or two additional arguments. If there is one additional argument, it specifies the number of numeric digits to include in the value (for example, <random:numeric:5> will generate a string of five numeric digits). If there are two additional arguments, they will specify the upper and lower bounds for a randomly-generated number (for example, <random:numeric:5:10> will generate a random integer between 5 and 10, inclusive).
This causes the tag to be replaced with a specified number of lowercase ASCII alphabetic characters (that is, the character set abcdefghijklmnopqrstuvwxyz) and/or numeric digits (that is, the character set 0123456789). This requires exactly one more argument, which is an integer specifying the number of characters to include in the generated value. For example, <random:alphanumeric:5> will generate a string of five randomly-selected alphanumeric characters.
This causes the tag to be replaced with characters from a user-defined character set. This can take either two or three additional arguments. The first additional argument is the characters for the user-defined character set. If there is a single argument after the character set, it specifies the number of characters to take from that set (for example, <random:chars:abcd:3> will cause three characters to be chosen in which each of those characters is either a, b, c, or d). If there are two arguments after the character set, they must be integer values and the number of characters generated will be an integer between this range (for example, <random:chars:abcd:3:5> will cause between 3 and 5 characters to be included in the value, where each character is either a, b, c, or d).
This causes the tag to be replaced with a specified number of hexadecimal characters (that is, the character set 0123456789abcdef). This requires exactly one more argument, which is an integer specifying the number of characters to include in the generated value. For example, <random:hex:5> will generate a string of five randomly-selected hexadecimal characters.
This causes the tag to be replaced with a specified number of characters allowed in the base64 character set (ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz01234567890+/). This requires exactly one more argument, which is an integer specifying the number of characters to include in the generated value. For example, <random:base64:5> will generate a string of five randomly-selected hexadecimal characters.
This causes the tag to be replaced with the name of a month of the year. If there are no additional arguments, the full name of the month is included (for example, <random:month> might return a value of October). If there is a single additional argument, it must be an integer value that specifies the maximum number of characters to include from the name of the month (for example, <random:month:3> might generate a value of Oct).
This causes the tag to be replaced with a randomly-generated telephone number in the format 123-456-7890. It does not take any additional arguments (that is, it should always be used like <random:telephone>).
This tag can be used in both branch and template definitions.
The RDN standard replacement tag is replaced with the RDN (that is, the leftmost DN component) of the current entry. If the RDN is not yet available (for example, because the RDN attribute has not yet been assigned a value in the entry being generated), it will be replaced with an empty string. In general, you should ensure that all RDN attributes are assigned values earlier in the template before this tag is used. The behavior of this tag is identical to that of the DN tag when used with a single argument whose value is one (that is, <dn:1>).
The RDN tag does not take any arguments. It can be used in both branch and template definitions.
The Sequential standard replacement tag is replaced with an integer value. Each entry is given a sequentially-incrementing value (for example, the first entry is given a value of zero, the next entry a value of one, and so on).
This tag can take zero, one, or two arguments:
If there are no arguments (that is, the tag is <sequential>), the first value will be zero, and the value will be reset to zero for each new branch.
If there is a single argument, it must be an integer that specifies the initial value to use (for example, a tag of <sequential:1000> will start generating values at 1000 instead of 0). The value will be reset to the specified initial value for each new branch.
If there are two arguments, the first must be an integer that specifies the initial value, and the second should be a Boolean value of either true or false indicating whether to reset the counter each time a new branch is started.
This tag can be used in both branch and template definitions.
The _DN (note the leading underscore character) standard replacement tag is replaced with the DN of the entry being generated, but with an underscore used instead of a comma between DN components. Apart from using underscores instead of commas, this works exactly like the DN tag. As such, it can also take an optional integer argument that specifies the number of components from the left (or from the right if the value is negative) should be included.
This tag can be used in both branch and template definitions.
The _ParentDN (note the leading underscore character) standard replacement tag is replaced with the DN of the parent entry of the entry being generated, but with an underscore used instead of a comma between DN components. This should always be available.
This tag does not take any arguments. It can only be used in template definitions. It cannot be used in branch definitions.
Attribute value reference tags can be used to replace the tag with the value of a specified attribute from the same entry. They are used by enclosing the name of the desired attribute in curly braces. For example, {cn} will be replaced with the value of the cn attribute, if it has already been given a value in the target entry. If the target attribute has not yet been given a value in the entry, the tag will be replaced with an empty string.
For example, consider the following excerpt from a template:
givenName: <first>
sn: <last>
uid: {givenName}.{sn}
cn: {givenName} {sn}
mail: {uid}@example.com
If the value chosen for the first name is Johnand the last name is Doe, then the resulting LDIF output would be:
givenName: John sn: Doe uid: John.Doe cn: John Doe mail: John.Doe@example.com
It is also possible to place a colon after the name of the attribute followed by a positive integer value specifying the maximum number of characters to include from the target attribute. For example, the template excerpt:
givenName: <first>
sn: <last>
initials: {givenName:1}{sn:1}
would cause the following LDIF to be generated:
givenName: John sn: Doe initials: JD
If the specified length is longer than the value of the named attribute, the entire value is used with no padding added. Otherwise, the specified number of characters are taken from the value.
All tags in the make-ldif syntax are currently given equal priority. As such, they are evaluated in the order that they appear in the template definition, from top to bottom, and from left to right within a given line. It is not possible to embed one tag within another.
The make-ldif utility has been designed in an extensible manner so that new tags can be defined and used in template files.
All tags must be subclasses of the org.opends.server.tools.makeldif.Tag abstract class. Custom tag definitions must include the following methods:
This retrieves the name that should be used to reference the tag. The value that it returns must be unique among all other tags in use by the server.
This indicates whether the tag will be allowed in branch definitions. If it returns a value of true, then the tag may be used in both branch and template definitions. If it returns a value of false, then the tag may be used in template definitions but not branch definitions.
This performs any initialization that may be required if the tag is to be used in a branch definition. This does not need to be implemented if allowedInBranch() returns false.
This performs any initialization that may be required of the tag is to be used in a template definition.
This performs any initialization that may be required before starting to generate entries below a new parent. This does not need to be implemented if no special initialization is required.
This generates the value that will be used to replace the associated tag when generating entries.
All of the tags available in make-ldif are included in the org.opends.server.tools.makeldif package. They may be used for reference to understand what is involved in implementing a custom tag.
Note - If you define a custom tag, ensure that it is available for use in any template file that might need it. This is done using the include statement, that should appear at the top of the template file. For more information, see Custom Tag Includes.
|