Importing and Exporting Data

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.

Populating a Stand-Alone Directory Server With Data

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:

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.

Importing Data Using import-ldif

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.

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.

import-ldif Operation Modes

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.

To Import Data in Offline Mode

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 the server if it is running.

$ stop-ds

Import the LDIF file, as shown in the following example:

$ 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).

To Replace Existing Data During an Offline Import

The following procedure replaces an existing back-end with new entries specified in an import
file.

To Import Fractional Files by Using Filters

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.

To Include or Exclude Attributes During Import

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 the server if it is running.

$ stop-ds

(Optional) View the entries of the import file before you start the import.

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:

To Record Rejected or Skipped Entries During Import

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 the server if it is running.

$ stop-ds

Import the file, using the --rejectFile and --skipFile options.

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.

To Import Data From a MakeLDIF Template

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 the server if it is running.

$ stop-ds

Import the data, using a template file.

The sample template generates 10,003 sample entries in the specified back end.

See Also

To Run an Import in Online Mode

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.

To Schedule an Import

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

See Also

Exporting Data Using export-ldif

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.

export-ldif Operation Modes

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.

To Export Part of a Back End by Using Filters

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.

To Include or Exclude Attributes During Export

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.

(Optional) With the server running, view a sample entry, by using the ldapsearch command.
For example:

To Run an Export in Online Mode

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.

Run the export-ldif command with the LDAP connection options. For example:

To Schedule an Export

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.

Run the export-ldif command with the --start option and the LDAP connection
parameters.

The --start option takes as its value a date and time in
the format yyyymmddhhmmss. For example:

Creating MakeLDIF Template Files

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.

The Template File Format

Template files can contain up to four sections, that must be provided in
the following order:

Custom Tag Includes

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.

Global Replacement Variables

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

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:

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:

o

Creates an entry with the organization object class.

ou

Creates an entry with the organizationalUnit object class.

c

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:

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.

Template Definitions

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.

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:

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.

make-ldif Template File Tags

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.

Standard Replacement 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 tag

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 tag

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:

cities

Contains a list of common city names

first.names

Contains a list of common first names

last.names

Contains a list of common last names

states

Contains a list of all two-character US state abbreviations

streets

Contains a list of common street names

This tag can be used in both branch and template definitions.

The First tag

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> tag does not take any arguments. It can be used in both branch and template definitions.

The IfAbsent tag

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.

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 tag

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.

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 tag

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 tag

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 tag

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 tag

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.

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 tag

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:

alpha

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.

numeric

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).

alphanumeric

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.

chars

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).

hex

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.

base64

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.

month

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).

telephone

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 tag

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 tag

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 tag

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 tag

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

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.

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.

Tag Evaluation Order

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.

Defining Custom Tags

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:

public String getName()

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.

public boolean allowedInBranch()

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 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.