makeldif

generate LDIF for import into a directory

Synopsis

install-path/dsrk/bin/makeldif 
 [options] -t template -o output.ldif

Description

The makeldif command generates LDAP Data Interchange Format (LDIF) files for import into a Lightweight Directory Access Protocol (LDAP) directory.

Options

The makeldif command supports the following options:

-b filename

Write bind information to this file when generating LDIF.

Lines of this file include a DN followed by a password, separated by a tab:

DN password

-C delimiter

Use the specified character instead of a comma when reading from a comma-separated format using the -c option.

-c filename

Use the specified comma-separated variable format file as input for generating LDIF.

-D

Run in debug mode, displaying additional information about errors.

-d filename

Write DNs to this file when generating LDIF.

-F filename

Write search filters constructed to find the entries generated to the specified file when generating search filters with the -T option.

-f filename

Use the specified file containing a list of first names to use when generating LDIF.

When this option is not used, the makeldif command uses the first.names file expected in the current directory.

-H

Display usage information and exit.

-I

Ignore the first line when reading from a comma-separated format using the -c option. Use this option when the initial line is a header not containing data.

-i attribute

Use values of the specified attribute as login IDs when writing login information using the -L option.

-L filename

Write login information to this file when generating LDIF.

Lines of this file include a login ID followed by a password, separated by a tab:

loginID    password

Specify the login ID attribute using the -i option. Default is uid.

-l filename

Use the specified file containing a list of last names to use when generating LDIF.

When this option is not used, the makeldif command uses the last.names file expected in the current directory.

-M

Generate a separate filter file for each relevant index type when generating search filters with the -T option.

-m maximum

Write no more than the specified maximum number of entries to a single file when generating LDIF.

Default is unlimited.

-o output.ldif

Create the specified file as output.

-N minimum

Only create filters that match at least the specified number of entries when generating substring search filters with the -T option.

Default is 1.

-n number

Create substring filters having the specified number of characters when generating substring search filters with the -T option.

Default is 3.

-S

Skip branch entries (parent entries) when generating LDIF.

-s number

Use the specified positive integer as a random number generator seed.

Default is to use a seed based on the current time.

You can consistently reproduce the same output by using the same random number generator seed and same templates.

-T attribute:types

Generate search filters of the specified types for the specified attributes.

The types is a comma-separated list of the following filter types:

eq: Filters matching for equality
sub: Filters matching substrings
subAny: Filters matching substrings anywhere within the string
subFinal: Filters matching substrings at the end of the attribute value
subInitial: Filters matching substrings at the beginning of the attribute value

-t template

Use the specified LDIF template file when generating LDIF.

Refer to EXTENDED DESCRIPTION for details.

-U

Always use UNIX-style newline characters (\n).

-V

Display version information and exit.

-w

Wrap long lines when generating LDIF.

Default is to write one attribute type and value per line, potentially resulting in very long lines for some values.

-X maximum

Only create filters that match no more than the specified number of entries when generating substring search filters with the -T option.

Default is unlimited.

-x maximum

Write no more than the specified maximum number of entries under each branch for each template when generating LDIF.

Default is unlimited.

Extended Description

The makeldif command relies on a template file to customize how entries in the generated LDIF are organized and what they contain. Template files may contain the following definitions:

Global Replacement Definitions: Define strings used to replace variables in the template file itself when generating LDIF
Branch Entry Definitions: Define branches in the directory information tree (DIT) structure
Template Definitions: Define how to generate leaf entries and attribute values

A sample you can customize, example.template, is installed with Directory Server Resource Kit.

Global Replacement Definitions

Replacement definitions define strings used to replace variables in the template itself. For example, the following line defines a variable called suffix having the value dc=example,dc=com:

define suffix=dc=example,dc=com

Given this definition, all subsequent occurrences of the string [suffix] in the template file are replaced with dc=example,dc=com. The replacement takes place when lines of the template file are read into memory, with the result that replacements happen even in branch definitions and like places where other tokens are not parsed. Notice that the variable is surrounded by brackets, []. When using brackets for purposes other than delimiting global replacement variables, escape them with a backslash, as in \[ or \]. The backslash characters are removed during LDIF generation.

Branch Entry Definitions

Branch entries are parents for other entries in a suffix. In other words, the branch entry at the root of the suffix for Example.com might be defined as:

branch: dc=example,dc=com

The makeldif command can then generate a corresponding branch entry represented in LDIF as follows:

dn: dc=example,dc=com
objectclass: top
objectclass: domain
dc=example

The makeldif command determines which object classes to use by examining the RDN of the entry, recognizing attribute types c (country), dc (domain component), l (location), o (organization), and ou (organizational unit). When you use RDNs having other attribute types, the makeldif command uses the object class extensibleObject for the entry.

To customize the branch entry itself, define additional attributes directly below the branch definition. For example, add a description attribute for the branch entry as follows:

branch: dc=example,dc=com
description: This is the description.

The resulting entry generated in LDIF appears as follows:

dn: dc=example,dc=com
objectclass: top
objectclass: domain
dc=example
description: This is the description.

To enable generation of entries below the branch entry, add subordinateTemplate definitions directly below the branch definition. For example, add a 1000 entries using the person template below ou=people,dc=example,dc=com as follows:

branch: ou=people,dc=example,dc=com
subordinateTemplate: person: 1000

You can add multiple subordinateTemplate definitions. For example, enable addition of 1000 entries using the person template and 500 entries using the personWithCertificate template below ou=people,dc=example,dc=com as follows:

branch: ou=people,dc=example,dc=com
subordinateTemplate: person: 1000
subordinateTemplate: personWithCertificate: 500

Template Definitions

Template definitions contain prototype entries with special tags allowing the makeldif command to generate many unique, custom entries. For example, a person template definition might appear as follows:

template: person
rdnAttr: uid
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
uid: {givenName}.{sn}
mail: {uid}@example.com
userPassword: <random:alphanumeric:8>
telephoneNumber: <random:telephone>

The first line of a template definition specifies the name of the template, here person. The makeldif command uses the name to identify the template when creating leaf entries under branch entries, based on subordinateTemplate definitions used with the branch entry definition. Each name must be unique.

A template entry may also have an rdnAttr line specifying the attribute type for the RDN of the generated entry. The rdnAttr takes a single value. Multi-valued RDNs are not supported. The default rdnAttr definition is cn if you do not provide one.

Other lines in a template definition reflect the attribute types and values to generate in the resulting LDIF. The makeldif command generates values for all recognized tokens.

Supported Attribute Value Tokens

The makeldif command support the following tokens:

<ancestordn:{depth}>

Replace this value with the DN of the entry's ancestor at the specified depth.

A depth of 1 specifies the parent entry; a depth of 2 specifies the grandparent, and so forth. If the entry does not have an ancestor at the specified depth, the makeldif command replaces the value with an empty string.

<base64:{value}>

Replace this value with a base64-encoded representation of the specified value.

The value is decoded to a byte array using the UTF-8 character set, and then the byte array is base64-encoded.

<base64:{charset}:{value}>

Replace this value with a base64-encoded representation of the specified value.

The value is decoded to a byte array using the specified character set, and then the byte array is base64-encoded.

<dn>

Replace this value with the DN of the current entry.

The RDN attribute for the entry must be assigned a value in the template before this token is used.

<exec:{command}>

Replace this value with the information sent to standard output when the specified command is executed on the system.

The replacement invokes a separate process each entry created using this template. Using this token can therefore slow LDIF generation considerably.

<exec:{command},{arg1},{arg2},…,{argN}>

Replace this value with the information sent to standard output when the specified command is executed on the system using the arguments provided.

The replacement invokes a separate process each entry created using this template. Using this token can therefore slow LDIF generation considerably.

<file:{filename}>

Replace this value with a randomly-chosen value from the specified file.

The file must contain one value per line. Weights cannot be assigned to the values in a file. To weight values, repeat their lines multiple times in the file.

<first>

Replace this value with a first name from the first name file specified using the -f option.

If both a first and last name are included in an entry, the combination of the first and last name is guaranteed to be unique. That is, no two entries in the generated LDIF file have the same combination of first and last name values. In order to guarantee uniqueness, the first and last names must be used in their entirety. You cannot use substrings of the form {givenName:5} for example.

<guid>

Replace this value with a GUID value in the containing hexadecimal digits in the form 12345678-90ab-cdef-1234-567890abcdef.

GUID values generated are unique within the LDIF generated.

<ifabsent:{attribute}>

Include this attribute only if the specified attribute is not present on the entry.

The specified attribute must be defined in the template file before it is referenced in the ifabsent tag.

<ifabsent:{attribute}:{value}>

Include this attribute only if the specified attribute is not present on the entry or if it does not have the specified value.

The specified attribute must be defined in the template file before it is referenced in the ifabsent tag. If the specified attribute has multiple values, the makeldif command checks only the first value.

<ifpresent:{attribute}>

Include this attribute only if the specified attribute is also present on the entry.

The specified attribute must be defined in the template file before it is referenced in the ifpresent tag.

<ifpresent:{attribute}:{value}>

Include this attribute only if the specified attribute is also present on the entry and has the specified value.

The specified attribute must be defined in the template file before it is referenced in the ifpresent tag. If the specified attribute has multiple values, the makeldif command checks only the first value.

<last>

Replace this value with a last name from the last name file specified using the -l option.

<list:{value1},{value2},…,{valueN}>

Replace this value with a randomly-chosen value from the specified, comma-delimited list.

Each value has an equal chance of being chosen.

<list:{value1}:{weight1},{value2}:{weight2},…,{valueN}:{weightN}>

Replace this value with a randomly-chosen value from the specified, comma-delimited list.

The weight associated with each list item determines how likely that value is to be chosen. A list item with a weight of 2 is twice as likely to be chosen as an item with a weight of 1. Specified only positive integer weights.

<loop:{start}:{end}>

Process this definition (end - start + 1) times, replacing this token each time with a number beginning at {start} and incrementing by one until reaching {end}.

You may include multiple loop tokens on the same line and using different {start} values, but only the first {end} value is used to determine how many copies of the line to create.

<parentdn>

Replace this value with the DN of the parent entry.

<presence:{percent}>

Include the attribute on the specified percentage of entries generated from this template definition. The percentage value is a number between 0 and 100.

Use this token only with attributes not required by the entry's object classes, and include something in the value of the attribute to be generated on entries including the attribute.

<random:alpha:{length}>

Replace this value with a string of {length} randomly-chosen alphabetic characters.

<random:alpha:{minlength}:{maxlength}>

Replace this value with a string of between {minlength} and {maxlength} randomly-chosen alphabetic characters.

<random:alphanumeric:{length}>

Replace this value with a string of {length} randomly-chosen alphanumeric characters.

<random:alphanumeric:{minlength}:{maxlength}>

Replace this value with a string of between {minlength} and {maxlength} randomly-chosen alphanumeric characters.

<random:base64:{length}>

Replace this value with a string of {length} randomly-chosen base64 characters.

If the specified length is not a multiple of 4, then the base64 value produced is padded with equal signs so that the total length is a multiple of 4.

<random:base64:{minlength}:{maxlength}>

Replace this value with a string of between {minlength} and {maxlength} randomly-chosen base64 characters.

<random:chars:{characters}:{length}>

Replace this value with a string of {length} characters that are randomly-selected from {characters}. {characters} may be any valid character other than the colon.

<random:hex:{length}>

Replace this value with a string of {length} randomly-chosen hexadecimal digits.

<random:hex:{minlength}:{maxlength}>

Replace this value with a string of between {minlength} and {maxlength} randomly-chosen hexadecimal digits.

<random:month>

Replace this value with the name of a randomly-chosen month. That is, t

The value is one of January, February, March, April, May, June, July, August, September, October, November, or December.

<random:month:{length}>

Replace this value with the first {length} characters of the name of a randomly-chosen month.

<random:numeric:{length}>

Replace this value with a string of {length} randomly-chosen numeric digits.

<random:numeric:{min}:{max}>

Replace this value with a randomly-chosen number between {min} and {max}, inclusive.

<random:numeric:{min}:{max}:{length}>

Replace this value with a randomly-chosen number between {min} and {max}, inclusive.

The value is padded with leading zeros so that it has at least {length} digits.

<random:telephone>

Replace this value with a string of randomly-chosen numeric digits in the form 123-456-7890.

This uses a US-format telephone number. You can generate telephone numbers in the format used by other countries by combining other random tags. For example, to generate a telephone number in the UK format, use +44 <random:numeric:4> <random:numeric:6>.

<sequential>

Replace this value with a sequentially-increasing numeric value.

The first value is zero. Sequential counters are separate on a per-attribute basis, so it is possible to use multiple sequential counters in the different attributes of the same entry without impacting each other.

<sequential:{firstvalue}>

Replace this value with a sequentially-increasing numeric value, where the first number starts at the specified value.

Sequential counters are separate on a per-attribute basis, so it is possible to use multiple sequential counters in different attributes of the same entry without impacting each other.

In addition to supported tokens, you can cause the makeldif command to generate attribute values from the values of attributes on the entry previously defined in the template by constructing prototype values using those attribute types in braces. For example, the following excerpt reuses givenName and sn (surname) values to define cn (common name) values:

…
givenName: <first>
sn: <last>
cn: {givenName} {sn}
…

When generating values from multi-valued attributes, the makeldif command uses the first value in the list.

To use only the first few characters of an attribute value to generate a value, add a colon followed by the length of the substring to use. For example, use {givenName:1}{sn:1}{employeeNumber} to generate values taking the first letter of the first name, followed by the first letter of the last name, followed by the employee number.

Subordinate Template Definitions

To create entries generated from one template definition below those generated by another template definition, include one or more subordinateTemplate definitions in the upper template definition.

Use this functionality with caution, however, as the makeldif command does not prevent you from generating circular references throwing the LDIF generation process into an infinite loop.

Inheritance

Template definitions support inheritance, whereby you specify a template definition that builds on a previously defined template, using the extends definition.

For example, to generate 10000 entries using the person template and an additional 1000 entries having the same structure as those generated from the person but also including a value for the userCertificate attribute, you create a template definition extending the person template as follows:

template: certificatePerson
rdnAttr: uid
extends: person
userCertificate: <random:base64:1000>

Given the person template defined previously, the certificatePerson template then has the same effect as the following:

template: certificatePerson
rdnAttr: uid
objectclass: top
objectclass: person
objectclass: organizationalPerson
objectclass: inetOrgPerson
givenName: <first>
sn: <last>
cn: {givenName} {sn}
uid: {givenName}.{sn}
mail: {uid}@example.com
userPassword: <random:alphanumeric:8>
telephoneNumber: <random:telephone>
userCertificate: <random:base64:1000>

You may use multiple levels of inheritance, but you must make sure both to specify the rdnAttr value for the inherited template as the parent's RDN attribute is not automatically used, and to avoid circular references that cause infinite loops in the LDIF generation process.

Examples

Examples in this section use the following conventions:

The makeldif command is found in a directory present in the PATH used for the examples.
The sample files are located in the current directory.

Example 1 makeldif: Generating LDIF

The following command generates LDIF using the sample template and other files delivered with Directory Server Resource Kit.

$ makeldif -t example.template -o sample.ldif
Processed 1000 entries
Processed 2000 entries
Processed 3000 entries
Processed 4000 entries
Processed 5000 entries
Processed 6000 entries
Processed 7000 entries
Processed 8000 entries
Processed 9000 entries
Processed 10000 entries
Processing complete.
10002 total entries written.

Example 2 makeldif: Generating Search Filters and LDIF

The following command generates LDIF and corresponding search filters base.

$ makeldif -T uid:eq -T cn:eq,sub -F filters.txt -t example.template -o sample.ldif
Processed 1000 entries
Processed 2000 entries
Processed 3000 entries
Processed 4000 entries
Processed 5000 entries
Processed 6000 entries
Processed 7000 entries
Processed 8000 entries
Processed 9000 entries
Processed 10000 entries
Processing complete.
10002 total entries written.
Writing filters to filters.txt
Wrote 10000 equality filters for uid
Wrote 10000 equality filters for cn
Wrote 1827 subInitial filters for cn
Wrote 7328 subAny filters for cn
Wrote 2099 subFinal filters for cn

Exit Status

The makeldif command exits with status 0 if it completes successfully. Otherwise it exits with non-zero status.

Attributes

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Availability	Zip distribution only
Stability Level	Evolving