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

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

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

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

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

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.

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.