external-software/github_OpenIdentityPlatform_OpenDJ.git

parent: fa2c2701 | patch | commit | show whitespace

Fix for OPENDJ-529: Documentation does not describe make-ldif template file...

Mark Craig

27.01.2012 461cd1c8bb33c54a43e0ae1e8b7033e1fd941fc0

Fix for OPENDJ-529: Documentation does not describe make-ldif template file format

2 files added

2 files modified

	opendj3/src/main/docbkx/admin-guide/index.xml	1 ●●●●● patch \| view \| raw \| blame \| history
	opendj3/src/main/docbkx/shared/man-make-ldif-template.xml	435 ●●●●● patch \| view \| raw \| blame \| history
	opendj3/src/main/docbkx/shared/man-make-ldif.xml	7 ●●●●● patch \| view \| raw \| blame \| history
	opends/resource/man/man5/make-ldif.template.5	509 ●●●●● patch \| view \| raw \| blame \| history

 opendj3/src/main/docbkx/admin-guide/index.xml

@@ -110,6 +110,7 @@
   <xinclude:include href='man-ldifsearch.xml' />
   <xinclude:include href='../shared/man-list-backends.xml' />
   <xinclude:include href='../shared/man-make-ldif.xml' />
   <xinclude:include href='../shared/man-make-ldif-template.xml' />
   <xinclude:include href='../shared/man-manage-account.xml' />
   <xinclude:include href='../shared/man-manage-tasks.xml' />
   <xinclude:include href='../shared/man-rebuild-index.xml' />

 opendj3/src/main/docbkx/shared/man-make-ldif-template.xml

New file
@@ -0,0 +1,435 @@
<?xml version="1.0" encoding="UTF-8"?>
<!--
  ! CCPL HEADER START
  !
  ! This work is licensed under the Creative Commons
  ! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
  ! To view a copy of this license, visit
  ! http://creativecommons.org/licenses/by-nc-nd/3.0/
  ! or send a letter to Creative Commons, 444 Castro Street,
  ! Suite 900, Mountain View, California, 94041, USA.
  !
  ! You can also obtain a copy of the license at
  ! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
  ! See the License for the specific language governing permissions
  ! and limitations under the License.
  !
  ! If applicable, add the following below this CCPL HEADER, with the fields
  ! enclosed by brackets "[]" replaced with your own identifying information:
  !      Portions Copyright [yyyy] [name of copyright owner]
  !
  ! CCPL HEADER END
  !
  !      Copyright 2012 ForgeRock AS
  !    
-->
<refentry xml:id='make-ldif-template-5'
 xmlns='http://docbook.org/ns/docbook'
 version='5.0' xml:lang='en'
 xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
 xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
 xmlns:xlink='http://www.w3.org/1999/xlink'
 xmlns:xinclude='http://www.w3.org/2001/XInclude'>
 <info><copyright><year>2012</year><holder>ForgeRock AS</holder></copyright></info>
 <refmeta>
  <refentrytitle>make-ldif.template</refentrytitle><manvolnum>5</manvolnum>
  <refmiscinfo class="software">OpenDJ</refmiscinfo>
  <refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
 </refmeta>
 <refnamediv>
  <refname>make-ldif.template</refname>
  <refpurpose>template file for the make-ldif command</refpurpose>
 </refnamediv>
 <refsynopsisdiv>
  <synopsis># Comment lines start with #.

# Optionally include classes that define custom tags.
# Custom tag classes extend org.opends.server.tools.makeldif.Tag and
# must be on the class path when you run make-ldif.
#
include <replaceable>custom.makeldif.tag.ClassName</replaceable>
...

# Optionally define constants used in the template.
# To reference constants later, put brackets around the name: [constant-name]
#
define <replaceable>constant-name</replaceable>=<replaceable>value</replaceable>
...

# Define branches by suffix DN, such as dc=example,dc=com;
# ou=People,dc=example,dc=com; ou=Groups,dc=example,dc=com; and so on.
# make-ldif generates the necessary object class definitions and RDNs.
#
# A branch can have subordinateTemplates that define templates to use for
# the branch entry.
#
# A branch can have additional attributes generated on the branch entry. See
# the Description below for more information on specifying attribute values.
#
branch: <replaceable>suffix-dn</replaceable>
[subordinateTemplate: <replaceable>template-name</replaceable>:<replaceable>number</replaceable>
...]
[<replaceable>attribute</replaceable>: <replaceable>attr-value</replaceable>
...]

...

# Define entries using templates.
#
# A template can extend another template.
# A template defines the RDN attribute(s) used for generated entries.
# A template can have a subordinateTemplate that defines a template to use for
# the generated entries.
#
# A template then defines attributes. See the Description below for more
# information on specifying attribute values.
#
template: <replaceable>template-name</replaceable>
[extends: <replaceable>template-name</replaceable>]
rdnAttr: <replaceable>attribute</replaceable>[+<replaceable>attribute</replaceable> ...]
[subordinateTemplate: <replaceable>template-name</replaceable>:<replaceable>number</replaceable>]
[<replaceable>attribute</replaceable>: <replaceable>attr-value</replaceable>
...]

...
</synopsis>
 </refsynopsisdiv>
 <refsect1>
  <title>Description</title>

  <para>Template files specify how to build LDIF. They allow you to define
  variables, insert random values from other files, and generally build
  arbitrarily large LDIF files for testing purposes. You pass template files
  to the <command>make-ldif</command> command when generating LDIF.</para>

  <para>The Synopsis above shows the layout for a <command>make-ldif</command>
  template file. This section focuses on what you can do to specify entry
  attribute values, called <replaceable>attr-value</replaceable> in the Synopsis
  section.</para>

  <variablelist>
   <title>Specifying Attribute Values</title>

   <para>When specifying attribute values in <command>make-ldif</command>
   templates, you can use static text and constants that you have defined,
   enclosing names for constants in brackets,
   <literal>[myConstant]</literal>.</para>

   <para>You can also use two kinds of tags when specifying attribute values.
   One kind of tag gets replaced with the value of another attribute in the
   generated entry. Such tags are delimited with braces, <literal>{ }</literal>.
   For example, if your template includes definitions for first name and last
   name attributes:</para>

   <programlisting>givenName: &lt;first&gt;
sn: &lt;last&gt;</programlisting>

   <para>Then you can define a mail attribute that uses the values of both
   attributes, and an initials attribute that takes the first character
   of each.</para>

   <programlisting>mail: {givenName}.{sn}@[myDomain]
initials: {givenName:1}{sn:1}</programlisting>

   <para>The other kind of tag is delimited with <literal>&lt;</literal>
   and <literal>&gt;</literal>, as shown above in the example with
   <literal>&lt;first&gt;</literal> and <literal>&lt;last&gt;</literal>.
   Tag names are not case sensitive. Many tags can take arguments separated
   by colons, <literal>:</literal>, from the tag names within the tag. OpenDJ
   supports the following tags.</para>

   <varlistentry>
    <term>&lt;DN&gt;</term>
    <listitem>
     <para>The DN tag gets replaced by the distinguished name of the current
     entry. An optional integer argument specifies the subcomponents of the DN
     to generate. For example, if the DN of the entry is
     <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>
     <literal>&lt;DN:1&gt;</literal> gets replaced by
     <literal>uid=bjensen</literal>, and <literal>&lt;DN:-2&gt;</literal> gets
     replaced by <literal>dc=example,dc=com</literal>.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;File&gt;</term>
    <listitem>
     <para>The File tag gets replaced by a line from a text file you specify.
     The File tag takes a required argument, the path to the text file, and an
     optional second argument, either <literal>random</literal> or
     <literal>sequential</literal>. For the file argument, either you specify
     an absolute path to the file such as
     <literal>&lt;file:/path/to/myDescriptions&gt;</literal>, or you specify
     a path relative to the
     <filename>/path/to/OpenDJ/config/MakeLDIF/</filename> directory such as
     <literal>&lt;file:streets&gt;</literal>. For the second argument,
     if you specify <literal>sequential</literal> then lines from the file are
     read in sequential order. Otherwise, lines from the file are read in
     random order.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;First&gt;</term>
    <listitem>
     <para>The first name tag gets replaced by a random line from
     <filename>/path/to/OpenDJ/config/MakeLDIF/first.names</filename>.
     Combinations of generated first and last names are unique, with integers
     appended to the name strings if not enough combinations are
     available.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;GUID&gt;</term>
    <listitem>
     <para>The GUID tag gets replaced by a 128-bit, type 4 (random) universally
     unique identifier, such as
     <literal>f47ac10b-58cc-4372-a567-0e02b2c3d479</literal>.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;IfAbsent&gt;</term>
    <listitem>
     <para>The IfAbsent tag takes as its first argument the name of another
     attribute, and optionally as its second argument a value to use. This tag
     causes the attribute to be generated only if the named attribute is not
     present on the generated entry. Use this tag when you have used
     <literal>&lt;Presence&gt;</literal> to define another attribute that is
     not always present on generated entries.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;IfPresent&gt;</term>
    <listitem>
     <para>The IfPresent takes as its first argument the name of another
     attribute, and optionally as its second argument a value to use. This tag
     causes the attribute to be generated only if the named attribute is also
     present on the generated entry. Use this tag when you have used
     <literal>&lt;Presence&gt;</literal> to define another attribute that is
     sometimes present on generated entries.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;Last&gt;</term>
    <listitem>
     <para>The last name tag gets replaced by a random line from
     <filename>/path/to/OpenDJ/config/MakeLDIF/last.names</filename>.
     Combinations of generated first and last names are unique, with integers
     appended to the name strings if not enough combinations are
     available.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;List&gt;</term>
    <listitem>
     <para>The List tag gets replaced by one of the values from the list of
     arguments you provide. For example,
     <literal>&lt;List:bronze:silver:gold&gt;</literal> gets replaced with
     <literal>bronze</literal>, <literal>silver</literal>, or
     <literal>gold</literal>.</para>
     <para>You can weight arguments to ensure some arguments are selected more
     often than others. For example, if you want two bronze for one silver
     and one gold, use
     <literal>&lt;List:bronze;2:silver;1:gold;1&gt;</literal>.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;ParentDN&gt;</term>
    <listitem>
     <para>The ParentDN tag gets replaced by the distinguished name of the
     parent entry. For example, if the DN of the entry is
     <literal>uid=bjensen,ou=People,dc=example,dc=com</literal>,
     <literal>&lt;ParentDN&gt;</literal> gets replaced by
     <literal>ou=People,dc=example,dc=com</literal>.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;Presence&gt;</term>
    <listitem>
     <para>The Presence tag takes a percent argument. It does not get replaced
     by a value itself, but instead results in the attribute being generated
     on the percentage of entries you specify in the argument. For example,
     <literal>description: &lt;Presence:50&gt;A description</literal> generates
     <literal>description: A description</literal> on half the entries.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;Random&gt;</term>
    <listitem>
     <para>The Random tag lets you generate a variety of random numbers and
     strings. The Random tag has the following subtypes, which you include
     as arguments, that is <literal>&lt;Random:<replaceable
     >subtype</replaceable>&gt;</literal>.</para>

     <itemizedlist>
      <listitem>
       <para><literal>alpha:<replaceable>length</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>alpha:<replaceable>minlength</replaceable>:<replaceable
       >maxlength</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>numeric:<replaceable>length</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>numeric:<replaceable>minvalue</replaceable>:<replaceable
       >maxvalue</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>numeric:<replaceable>minvalue</replaceable>:<replaceable
       >maxvalue</replaceable>:<replaceable>format</replaceable></literal>,
       where <replaceable>format</replaceable> is a
       <literal>java.text.DecimalFormat</literal> pattern</para>
      </listitem>
      <listitem>
       <para><literal>alphanumeric:<replaceable>length</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>alphanumeric:<replaceable>minlength</replaceable>:<replaceable
       >maxlength</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>chars:<replaceable>characters</replaceable>:<replaceable
       >length</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>chars:<replaceable>characters</replaceable>:<replaceable
       >minlength</replaceable>:<replaceable>maxlength</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>hex:<replaceable>length</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>hex:<replaceable>minlength</replaceable>:<replaceable
       >maxlength</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>base64:<replaceable>length</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>base64:<replaceable>minlength</replaceable>:<replaceable
       >maxlength</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>month</literal></para>
      </listitem>
      <listitem>
       <para><literal>month:<replaceable>maxlength</replaceable></literal></para>
      </listitem>
      <listitem>
       <para><literal>telephone</literal>, a telephone number starting with
       the country code <literal>+1</literal></para>
      </listitem>
     </itemizedlist>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;RDN&gt;</term>
    <listitem>
     <para>The RDN tag gets replaced with the RDN of the entry. Use this
     in the template after you have specified <literal>rdnAttr</literal> so
     that the RDN has already been generated when this tag is replaced.</para>

     <para>An optional integer argument specifies the subcomponents of the RDN
     to generate.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;Sequential&gt;</term>
    <listitem>
     <para>The Sequential tag gets replaced by a sequentially increasing
     generated integer. The first optional integer argument specifies the
     starting number. The second optional boolean argument specifies whether
     to start over when generating entries for a new parent entry. For example,
     <literal>&lt;Sequential&gt;:42:true</literal> starts counting from 42,
     and starts over when the parent entry changes from
     <literal>o=Engineering</literal> to <literal>o=Marketing</literal>.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;_DN&gt;</term>
    <listitem>
     <para>The _DN tag gets replaced by the DN of the current entry with
     underscores in the place of commas.</para>
    </listitem>
   </varlistentry>

   <varlistentry>
    <term>&lt;_ParentDN&gt;</term>
    <listitem>
     <para>The _ParentDN tag gets replaced by the DN the parent entry with
     underscores in the place of commas.</para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>
 <refsect1>
  <title>Examples</title>
  <para>The following example generates 10 organization units, each containing
  50 entries.</para>

  <programlisting language="ldif">define suffix=dc=example,dc=com
define maildomain=example.com
define numusers=50
define numorgs=10

branch: [suffix]

branch: ou=People,[suffix]
subordinateTemplate: orgunit:[numorgs]
description: This is the People container
telephoneNumber: +33 00010002

template: orgunit
subordinateTemplate: person:[numusers]
rdnAttr: ou
ou: Org-&lt;sequential:0&gt;
objectClass: top
objectClass: organizationalUnit
description: This is the {ou} organizational unit

template: person
rdnAttr: uid
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
givenName: &lt;first&gt;
sn: &lt;last&gt;
cn: {givenName} {sn}
initials: {givenName:1}&lt;random:chars:ABCDEFGHIJKLMNOPQRSTUVWXYZ:1&gt;{sn:1}
employeeNumber: &lt;sequential:0&gt;
uid: user.{employeeNumber}
mail: {uid}@[maildomain]
userPassword: password
telephoneNumber: &lt;random:telephone&gt;
homePhone: &lt;random:telephone&gt;
pager: &lt;random:telephone&gt;
mobile: &lt;random:telephone&gt;
street: &lt;random:numeric:5&gt; &lt;file:streets&gt; Street
l: &lt;file:cities&gt;
st: &lt;file:states&gt;
postalCode: &lt;random:numeric:5&gt;
postalAddress: {cn}${street}${l}, {st}  {postalCode}
description: This is the description for {cn}.</programlisting>
 </refsect1>
 <refsect1>
  <title>See Also</title>
  <para><link xlink:href="admin-guide#make-ldif-1"
  xlink:role="http://docbook.org/xlink/role/olink"><citerefentry><refentrytitle
  >make-ldif</refentrytitle><manvolnum>1</manvolnum></citerefentry></link
  >, <filename>/path/to/OpenDJ/config/MakeLDIF/example.template</filename></para>
 </refsect1>
</refentry>

 opendj3/src/main/docbkx/shared/man-make-ldif.xml

@@ -116,4 +116,11 @@
Processed 10000 entries
LDIF processing complete.  10003 entries written</screen>
 </refsect1>
 <refsect1>
  <title>See Also</title>
  <para><link xlink:href="admin-guide#make-ldif-template-5"
  xlink:role="http://docbook.org/xlink/role/olink"><citerefentry><refentrytitle
  >make-ldif.template</refentrytitle><manvolnum>5</manvolnum
  ></citerefentry></link></para>
 </refsect1>
</refentry>

 opends/resource/man/man5/make-ldif.template.5

New file
@@ -0,0 +1,509 @@
'\" t
.\"     Title: make-ldif.template
.\"    Author: 
.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 06/27/2012
.\"    Manual: Tools Reference
.\"    Source: OpenDJ 2.5.0
.\"  Language: English
.\"
.TH "MAKE\-LDIF\&.TEMPLAT" "5" "06/27/2012" "OpenDJ 2\&.5\&.0" "Tools Reference"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
make-ldif.template \- template file for the make\-ldif command
.SH "SYNOPSIS"
.sp
.nf
# Comment lines start with #\&.

# Optionally include classes that define custom tags\&.
# Custom tag classes extend org\&.opends\&.server\&.tools\&.makeldif\&.Tag and
# must be on the class path when you run make\-ldif\&.
#
include \fIcustom\&.makeldif\&.tag\&.ClassName\fR
\&.\&.\&.

# Optionally define constants used in the template\&.
# To reference constants later, put brackets around the name: [constant\-name]
#
define \fIconstant\-name\fR=\fIvalue\fR
\&.\&.\&.

# Define branches by suffix DN, such as dc=example,dc=com;
# ou=People,dc=example,dc=com; ou=Groups,dc=example,dc=com; and so on\&.
# make\-ldif generates the necessary object class definitions and RDNs\&.
#
# A branch can have subordinateTemplates that define templates to use for
# the branch entry\&.
#
# A branch can have additional attributes generated on the branch entry\&. See
# the Description below for more information on specifying attribute values\&.
#
branch: \fIsuffix\-dn\fR
[subordinateTemplate: \fItemplate\-name\fR:\fInumber\fR
\&.\&.\&.]
[\fIattribute\fR: \fIattr\-value\fR
\&.\&.\&.]

\&.\&.\&.

# Define entries using templates\&.
#
# A template can extend another template\&.
# A template defines the RDN attribute(s) used for generated entries\&.
# A template can have a subordinateTemplate that defines a template to use for
# the generated entries\&.
#
# A template then defines attributes\&. See the Description below for more
# information on specifying attribute values\&.
#
template: \fItemplate\-name\fR
[extends: \fItemplate\-name\fR]
rdnAttr: \fIattribute\fR[+\fIattribute\fR \&.\&.\&.]
[subordinateTemplate: \fItemplate\-name\fR:\fInumber\fR]
[\fIattribute\fR: \fIattr\-value\fR
\&.\&.\&.]

\&.\&.\&.
.fi
.SH "DESCRIPTION"
.PP
Template files specify how to build LDIF\&. They allow you to define variables, insert random values from other files, and generally build arbitrarily large LDIF files for testing purposes\&. You pass template files to the
\fBmake\-ldif\fR
command when generating LDIF\&.
.PP
The Synopsis above shows the layout for a
\fBmake\-ldif\fR
template file\&. This section focuses on what you can do to specify entry attribute values, called
\fIattr\-value\fR
in the Synopsis section\&.
.PP
\fBSpecifying Attribute Values\fR
.PP
When specifying attribute values in
\fBmake\-ldif\fR
templates, you can use static text and constants that you have defined, enclosing names for constants in brackets,
[myConstant]\&.
.PP
You can also use two kinds of tags when specifying attribute values\&. One kind of tag gets replaced with the value of another attribute in the generated entry\&. Such tags are delimited with braces,
{ }\&. For example, if your template includes definitions for first name and last name attributes:
.sp
.if n \{\
.RS 4
.\}
.nf
givenName: <first>
sn: <last>
.fi
.if n \{\
.RE
.\}
.PP
Then you can define a mail attribute that uses the values of both attributes, and an initials attribute that takes the first character of each\&.
.sp
.if n \{\
.RS 4
.\}
.nf
mail: {givenName}\&.{sn}@[myDomain]
initials: {givenName:1}{sn:1}
.fi
.if n \{\
.RE
.\}
.PP
The other kind of tag is delimited with
<
and
>, as shown above in the example with
<first>
and
<last>\&. Tag names are not case sensitive\&. Many tags can take arguments separated by colons,
:, from the tag names within the tag\&. OpenDJ supports the following tags\&.
.PP
<DN>
.RS 4
The DN tag gets replaced by the distinguished name of the current entry\&. An optional integer argument specifies the subcomponents of the DN to generate\&. For example, if the DN of the entry is
uid=bjensen,ou=People,dc=example,dc=com
<DN:1>
gets replaced by
uid=bjensen, and
<DN:\-2>
gets replaced by
dc=example,dc=com\&.
.RE
.PP
<File>
.RS 4
The File tag gets replaced by a line from a text file you specify\&. The File tag takes a required argument, the path to the text file, and an optional second argument, either
random
or
sequential\&. For the file argument, either you specify an absolute path to the file such as
<file:/path/to/myDescriptions>, or you specify a path relative to the
/path/to/OpenDJ/config/MakeLDIF/
directory such as
<file:streets>\&. For the second argument, if you specify
sequential
then lines from the file are read in sequential order\&. Otherwise, lines from the file are read in random order\&.
.RE
.PP
<First>
.RS 4
The first name tag gets replaced by a random line from
/path/to/OpenDJ/config/MakeLDIF/first\&.names\&. Combinations of generated first and last names are unique, with integers appended to the name strings if not enough combinations are available\&.
.RE
.PP
<GUID>
.RS 4
The GUID tag gets replaced by a 128\-bit, type 4 (random) universally unique identifier, such as
f47ac10b\-58cc\-4372\-a567\-0e02b2c3d479\&.
.RE
.PP
<IfAbsent>
.RS 4
The IfAbsent tag takes as its first argument the name of another attribute, and optionally as its second argument a value to use\&. This tag causes the attribute to be generated only if the named attribute is not present on the generated entry\&. Use this tag when you have used
<Presence>
to define another attribute that is not always present on generated entries\&.
.RE
.PP
<IfPresent>
.RS 4
The IfPresent takes as its first argument the name of another attribute, and optionally as its second argument a value to use\&. This tag causes the attribute to be generated only if the named attribute is also present on the generated entry\&. Use this tag when you have used
<Presence>
to define another attribute that is sometimes present on generated entries\&.
.RE
.PP
<Last>
.RS 4
The last name tag gets replaced by a random line from
/path/to/OpenDJ/config/MakeLDIF/last\&.names\&. Combinations of generated first and last names are unique, with integers appended to the name strings if not enough combinations are available\&.
.RE
.PP
<List>
.RS 4
The List tag gets replaced by one of the values from the list of arguments you provide\&. For example,
<List:bronze:silver:gold>
gets replaced with
bronze,
silver, or
gold\&.
.sp
You can weight arguments to ensure some arguments are selected more often than others\&. For example, if you want two bronze for one silver and one gold, use
<List:bronze;2:silver;1:gold;1>\&.
.RE
.PP
<ParentDN>
.RS 4
The ParentDN tag gets replaced by the distinguished name of the parent entry\&. For example, if the DN of the entry is
uid=bjensen,ou=People,dc=example,dc=com,
<ParentDN>
gets replaced by
ou=People,dc=example,dc=com\&.
.RE
.PP
<Presence>
.RS 4
The Presence tag takes a percent argument\&. It does not get replaced by a value itself, but instead results in the attribute being generated on the percentage of entries you specify in the argument\&. For example,
description: <Presence:50>A description
generates
description: A description
on half the entries\&.
.RE
.PP
<Random>
.RS 4
The Random tag lets you generate a variety of random numbers and strings\&. The Random tag has the following subtypes, which you include as arguments, that is
<Random:\fIsubtype\fR>\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
alpha:\fIlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
alpha:\fIminlength\fR:\fImaxlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
numeric:\fIlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
numeric:\fIminvalue\fR:\fImaxvalue\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
numeric:\fIminvalue\fR:\fImaxvalue\fR:\fIformat\fR, where
\fIformat\fR
is a
java\&.text\&.DecimalFormat
pattern
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
alphanumeric:\fIlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
alphanumeric:\fIminlength\fR:\fImaxlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
chars:\fIcharacters\fR:\fIlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
chars:\fIcharacters\fR:\fIminlength\fR:\fImaxlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
hex:\fIlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
hex:\fIminlength\fR:\fImaxlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
base64:\fIlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
base64:\fIminlength\fR:\fImaxlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
month
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
month:\fImaxlength\fR
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
telephone, a telephone number starting with the country code
+1
.RE
.RE
.PP
<RDN>
.RS 4
The RDN tag gets replaced with the RDN of the entry\&. Use this in the template after you have specified
rdnAttr
so that the RDN has already been generated when this tag is replaced\&.
.sp
An optional integer argument specifies the subcomponents of the RDN to generate\&.
.RE
.PP
<Sequential>
.RS 4
The Sequential tag gets replaced by a sequentially increasing generated integer\&. The first optional integer argument specifies the starting number\&. The second optional boolean argument specifies whether to start over when generating entries for a new parent entry\&. For example,
<Sequential>:42:true
starts counting from 42, and starts over when the parent entry changes from
o=Engineering
to
o=Marketing\&.
.RE
.PP
<_DN>
.RS 4
The _DN tag gets replaced by the DN of the current entry with underscores in the place of commas\&.
.RE
.PP
<_ParentDN>
.RS 4
The _ParentDN tag gets replaced by the DN the parent entry with underscores in the place of commas\&.
.RE
.SH "EXAMPLES"
.PP
The following example generates 10 organization units, each containing 50 entries\&.
.sp
.if n \{\
.RS 4
.\}
.nf
define suffix=dc=example,dc=com
define maildomain=example\&.com
define numusers=50
define numorgs=10

branch: [suffix]

branch: ou=People,[suffix]
subordinateTemplate: orgunit:[numorgs]
description: This is the People container
telephoneNumber: +33 00010002

template: orgunit
subordinateTemplate: person:[numusers]
rdnAttr: ou
ou: Org\-<sequential:0>
objectClass: top
objectClass: organizationalUnit
description: This is the {ou} organizational unit

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}\&.
.fi
.if n \{\
.RE
.\}
.SH "SEE ALSO"
.PP
\m[blue]\fB\fBmake-ldif\fR(1)\fR\m[],
/path/to/OpenDJ/config/MakeLDIF/example\&.template
.SH "COPYRIGHT"
.br
Copyright \(co 2012 ForgeRock AS
.br

			@@ -110,6 +110,7 @@
			<xinclude:include href='man-ldifsearch.xml' />
			<xinclude:include href='../shared/man-list-backends.xml' />
			<xinclude:include href='../shared/man-make-ldif.xml' />
			<xinclude:include href='../shared/man-make-ldif-template.xml' />
			<xinclude:include href='../shared/man-manage-account.xml' />
			<xinclude:include href='../shared/man-manage-tasks.xml' />
			<xinclude:include href='../shared/man-rebuild-index.xml' />

New file
			@@ -0,0 +1,435 @@
			<?xml version="1.0" encoding="UTF-8"?>
			<!--
			! CCPL HEADER START
			!
			! This work is licensed under the Creative Commons
			! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
			! To view a copy of this license, visit
			! http://creativecommons.org/licenses/by-nc-nd/3.0/
			! or send a letter to Creative Commons, 444 Castro Street,
			! Suite 900, Mountain View, California, 94041, USA.
			!
			! You can also obtain a copy of the license at
			! trunk/opendj3/legal-notices/CC-BY-NC-ND.txt.
			! See the License for the specific language governing permissions
			! and limitations under the License.
			!
			! If applicable, add the following below this CCPL HEADER, with the fields
			! enclosed by brackets "[]" replaced with your own identifying information:
			! Portions Copyright [yyyy] [name of copyright owner]
			!
			! CCPL HEADER END
			!
			! Copyright 2012 ForgeRock AS
			!
			-->
			<refentry xml:id='make-ldif-template-5'
			xmlns='http://docbook.org/ns/docbook'
			version='5.0' xml:lang='en'
			xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
			xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
			xmlns:xlink='http://www.w3.org/1999/xlink'
			xmlns:xinclude='http://www.w3.org/2001/XInclude'>
			<info><copyright><year>2012</year><holder>ForgeRock AS</holder></copyright></info>
			<refmeta>
			<refentrytitle>make-ldif.template</refentrytitle><manvolnum>5</manvolnum>
			<refmiscinfo class="software">OpenDJ</refmiscinfo>
			<refmiscinfo class="version"><?eval ${docTargetVersion}?></refmiscinfo>
			</refmeta>
			<refnamediv>
			<refname>make-ldif.template</refname>
			<refpurpose>template file for the make-ldif command</refpurpose>
			</refnamediv>
			<refsynopsisdiv>
			<synopsis># Comment lines start with #.

			# Optionally include classes that define custom tags.
			# Custom tag classes extend org.opends.server.tools.makeldif.Tag and
			# must be on the class path when you run make-ldif.
			#
			include <replaceable>custom.makeldif.tag.ClassName</replaceable>
			...

			# Optionally define constants used in the template.
			# To reference constants later, put brackets around the name: [constant-name]
			#
			define <replaceable>constant-name</replaceable>=<replaceable>value</replaceable>
			...

			# Define branches by suffix DN, such as dc=example,dc=com;
			# ou=People,dc=example,dc=com; ou=Groups,dc=example,dc=com; and so on.
			# make-ldif generates the necessary object class definitions and RDNs.
			#
			# A branch can have subordinateTemplates that define templates to use for
			# the branch entry.
			#
			# A branch can have additional attributes generated on the branch entry. See
			# the Description below for more information on specifying attribute values.
			#
			branch: <replaceable>suffix-dn</replaceable>
			[subordinateTemplate: <replaceable>template-name</replaceable>:<replaceable>number</replaceable>
			...]
			[<replaceable>attribute</replaceable>: <replaceable>attr-value</replaceable>
			...]

			...

			# Define entries using templates.
			#
			# A template can extend another template.
			# A template defines the RDN attribute(s) used for generated entries.
			# A template can have a subordinateTemplate that defines a template to use for
			# the generated entries.
			#
			# A template then defines attributes. See the Description below for more
			# information on specifying attribute values.
			#
			template: <replaceable>template-name</replaceable>
			[extends: <replaceable>template-name</replaceable>]
			rdnAttr: <replaceable>attribute</replaceable>[+<replaceable>attribute</replaceable> ...]
			[subordinateTemplate: <replaceable>template-name</replaceable>:<replaceable>number</replaceable>]
			[<replaceable>attribute</replaceable>: <replaceable>attr-value</replaceable>
			...]

			...
			</synopsis>
			</refsynopsisdiv>
			<refsect1>
			<title>Description</title>

			<para>Template files specify how to build LDIF. They allow you to define
			variables, insert random values from other files, and generally build
			arbitrarily large LDIF files for testing purposes. You pass template files
			to the <command>make-ldif</command> command when generating LDIF.</para>

			<para>The Synopsis above shows the layout for a <command>make-ldif</command>
			template file. This section focuses on what you can do to specify entry
			attribute values, called <replaceable>attr-value</replaceable> in the Synopsis
			section.</para>

			<variablelist>
			<title>Specifying Attribute Values</title>

			<para>When specifying attribute values in <command>make-ldif</command>
			templates, you can use static text and constants that you have defined,
			enclosing names for constants in brackets,
			<literal>[myConstant]</literal>.</para>

			<para>You can also use two kinds of tags when specifying attribute values.
			One kind of tag gets replaced with the value of another attribute in the
			generated entry. Such tags are delimited with braces, <literal>{ }</literal>.
			For example, if your template includes definitions for first name and last
			name attributes:</para>

			<programlisting>givenName: <first>
			sn: <last></programlisting>

			<para>Then you can define a mail attribute that uses the values of both
			attributes, and an initials attribute that takes the first character
			of each.</para>

			<programlisting>mail: {givenName}.{sn}@[myDomain]
			initials: {givenName:1}{sn:1}</programlisting>

			<para>The other kind of tag is delimited with <literal><</literal>
			and <literal>></literal>, as shown above in the example with
			<literal><first></literal> and <literal><last></literal>.
			Tag names are not case sensitive. Many tags can take arguments separated
			by colons, <literal>:</literal>, from the tag names within the tag. OpenDJ
			supports the following tags.</para>

			<varlistentry>
			<term><DN></term>
			<listitem>
			<para>The DN tag gets replaced by the distinguished name of the current
			entry. An optional integer argument specifies the subcomponents of the DN
			to generate. For example, if the DN of the entry is
			<literal>uid=bjensen,ou=People,dc=example,dc=com</literal>
			<literal><DN:1></literal> gets replaced by
			<literal>uid=bjensen</literal>, and <literal><DN:-2></literal> gets
			replaced by <literal>dc=example,dc=com</literal>.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><File></term>
			<listitem>
			<para>The File tag gets replaced by a line from a text file you specify.
			The File tag takes a required argument, the path to the text file, and an
			optional second argument, either <literal>random</literal> or
			<literal>sequential</literal>. For the file argument, either you specify
			an absolute path to the file such as
			<literal><file:/path/to/myDescriptions></literal>, or you specify
			a path relative to the
			<filename>/path/to/OpenDJ/config/MakeLDIF/</filename> directory such as
			<literal><file:streets></literal>. For the second argument,
			if you specify <literal>sequential</literal> then lines from the file are
			read in sequential order. Otherwise, lines from the file are read in
			random order.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><First></term>
			<listitem>
			<para>The first name tag gets replaced by a random line from
			<filename>/path/to/OpenDJ/config/MakeLDIF/first.names</filename>.
			Combinations of generated first and last names are unique, with integers
			appended to the name strings if not enough combinations are
			available.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><GUID></term>
			<listitem>
			<para>The GUID tag gets replaced by a 128-bit, type 4 (random) universally
			unique identifier, such as
			<literal>f47ac10b-58cc-4372-a567-0e02b2c3d479</literal>.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><IfAbsent></term>
			<listitem>
			<para>The IfAbsent tag takes as its first argument the name of another
			attribute, and optionally as its second argument a value to use. This tag
			causes the attribute to be generated only if the named attribute is not
			present on the generated entry. Use this tag when you have used
			<literal><Presence></literal> to define another attribute that is
			not always present on generated entries.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><IfPresent></term>
			<listitem>
			<para>The IfPresent takes as its first argument the name of another
			attribute, and optionally as its second argument a value to use. This tag
			causes the attribute to be generated only if the named attribute is also
			present on the generated entry. Use this tag when you have used
			<literal><Presence></literal> to define another attribute that is
			sometimes present on generated entries.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><Last></term>
			<listitem>
			<para>The last name tag gets replaced by a random line from
			<filename>/path/to/OpenDJ/config/MakeLDIF/last.names</filename>.
			Combinations of generated first and last names are unique, with integers
			appended to the name strings if not enough combinations are
			available.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><List></term>
			<listitem>
			<para>The List tag gets replaced by one of the values from the list of
			arguments you provide. For example,
			<literal><List:bronze:silver:gold></literal> gets replaced with
			<literal>bronze</literal>, <literal>silver</literal>, or
			<literal>gold</literal>.</para>
			<para>You can weight arguments to ensure some arguments are selected more
			often than others. For example, if you want two bronze for one silver
			and one gold, use
			<literal><List:bronze;2:silver;1:gold;1></literal>.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><ParentDN></term>
			<listitem>
			<para>The ParentDN tag gets replaced by the distinguished name of the
			parent entry. For example, if the DN of the entry is
			<literal>uid=bjensen,ou=People,dc=example,dc=com</literal>,
			<literal><ParentDN></literal> gets replaced by
			<literal>ou=People,dc=example,dc=com</literal>.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><Presence></term>
			<listitem>
			<para>The Presence tag takes a percent argument. It does not get replaced
			by a value itself, but instead results in the attribute being generated
			on the percentage of entries you specify in the argument. For example,
			<literal>description: <Presence:50>A description</literal> generates
			<literal>description: A description</literal> on half the entries.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><Random></term>
			<listitem>
			<para>The Random tag lets you generate a variety of random numbers and
			strings. The Random tag has the following subtypes, which you include
			as arguments, that is <literal><Random:<replaceable
			>subtype</replaceable>></literal>.</para>

			<itemizedlist>
			<listitem>
			<para><literal>alpha:<replaceable>length</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>alpha:<replaceable>minlength</replaceable>:<replaceable
			>maxlength</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>numeric:<replaceable>length</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>numeric:<replaceable>minvalue</replaceable>:<replaceable
			>maxvalue</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>numeric:<replaceable>minvalue</replaceable>:<replaceable
			>maxvalue</replaceable>:<replaceable>format</replaceable></literal>,
			where <replaceable>format</replaceable> is a
			<literal>java.text.DecimalFormat</literal> pattern</para>
			</listitem>
			<listitem>
			<para><literal>alphanumeric:<replaceable>length</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>alphanumeric:<replaceable>minlength</replaceable>:<replaceable
			>maxlength</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>chars:<replaceable>characters</replaceable>:<replaceable
			>length</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>chars:<replaceable>characters</replaceable>:<replaceable
			>minlength</replaceable>:<replaceable>maxlength</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>hex:<replaceable>length</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>hex:<replaceable>minlength</replaceable>:<replaceable
			>maxlength</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>base64:<replaceable>length</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>base64:<replaceable>minlength</replaceable>:<replaceable
			>maxlength</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>month</literal></para>
			</listitem>
			<listitem>
			<para><literal>month:<replaceable>maxlength</replaceable></literal></para>
			</listitem>
			<listitem>
			<para><literal>telephone</literal>, a telephone number starting with
			the country code <literal>+1</literal></para>
			</listitem>
			</itemizedlist>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><RDN></term>
			<listitem>
			<para>The RDN tag gets replaced with the RDN of the entry. Use this
			in the template after you have specified <literal>rdnAttr</literal> so
			that the RDN has already been generated when this tag is replaced.</para>

			<para>An optional integer argument specifies the subcomponents of the RDN
			to generate.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><Sequential></term>
			<listitem>
			<para>The Sequential tag gets replaced by a sequentially increasing
			generated integer. The first optional integer argument specifies the
			starting number. The second optional boolean argument specifies whether
			to start over when generating entries for a new parent entry. For example,
			<literal><Sequential>:42:true</literal> starts counting from 42,
			and starts over when the parent entry changes from
			<literal>o=Engineering</literal> to <literal>o=Marketing</literal>.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><_DN></term>
			<listitem>
			<para>The _DN tag gets replaced by the DN of the current entry with
			underscores in the place of commas.</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term><_ParentDN></term>
			<listitem>
			<para>The _ParentDN tag gets replaced by the DN the parent entry with
			underscores in the place of commas.</para>
			</listitem>
			</varlistentry>
			</variablelist>
			</refsect1>
			<refsect1>
			<title>Examples</title>
			<para>The following example generates 10 organization units, each containing
			50 entries.</para>

			<programlisting language="ldif">define suffix=dc=example,dc=com
			define maildomain=example.com
			define numusers=50
			define numorgs=10

			branch: [suffix]

			branch: ou=People,[suffix]
			subordinateTemplate: orgunit:[numorgs]
			description: This is the People container
			telephoneNumber: +33 00010002

			template: orgunit
			subordinateTemplate: person:[numusers]
			rdnAttr: ou
			ou: Org-<sequential:0>
			objectClass: top
			objectClass: organizationalUnit
			description: This is the {ou} organizational unit

			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}.</programlisting>
			</refsect1>
			<refsect1>
			<title>See Also</title>
			<para><link xlink:href="admin-guide#make-ldif-1"
			xlink:role="http://docbook.org/xlink/role/olink"><citerefentry><refentrytitle
			>make-ldif</refentrytitle><manvolnum>1</manvolnum></citerefentry></link
			>, <filename>/path/to/OpenDJ/config/MakeLDIF/example.template</filename></para>
			</refsect1>
			</refentry>

			@@ -116,4 +116,11 @@
			Processed 10000 entries
			LDIF processing complete. 10003 entries written</screen>
			</refsect1>
			<refsect1>
			<title>See Also</title>
			<para><link xlink:href="admin-guide#make-ldif-template-5"
			xlink:role="http://docbook.org/xlink/role/olink"><citerefentry><refentrytitle
			>make-ldif.template</refentrytitle><manvolnum>5</manvolnum
			></citerefentry></link></para>
			</refsect1>
			</refentry>

New file
			@@ -0,0 +1,509 @@
			'\" t
			.\" Title: make-ldif.template
			.\" Author:
			.\" Generator: DocBook XSL-NS Stylesheets v1.76.1 <http://docbook.sf.net/>
			.\" Date: 06/27/2012
			.\" Manual: Tools Reference
			.\" Source: OpenDJ 2.5.0
			.\" Language: English
			.\"
			.TH "MAKE\-LDIF\&.TEMPLAT" "5" "06/27/2012" "OpenDJ 2\&.5\&.0" "Tools Reference"
			.\" -----------------------------------------------------------------
			.\" * Define some portability stuff
			.\" -----------------------------------------------------------------
			.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
			.\" http://bugs.debian.org/507673
			.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
			.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
			.ie \n(.g .ds Aq \(aq
			.el .ds Aq '
			.\" -----------------------------------------------------------------
			.\" * set default formatting
			.\" -----------------------------------------------------------------
			.\" disable hyphenation
			.nh
			.\" disable justification (adjust text to left margin only)
			.ad l
			.\" -----------------------------------------------------------------
			.\" * MAIN CONTENT STARTS HERE *
			.\" -----------------------------------------------------------------
			.SH "NAME"
			make-ldif.template \- template file for the make\-ldif command
			.SH "SYNOPSIS"
			.sp
			.nf
			# Comment lines start with #\&.

			# Optionally include classes that define custom tags\&.
			# Custom tag classes extend org\&.opends\&.server\&.tools\&.makeldif\&.Tag and
			# must be on the class path when you run make\-ldif\&.
			#
			include \fIcustom\&.makeldif\&.tag\&.ClassName\fR
			\&.\&.\&.

			# Optionally define constants used in the template\&.
			# To reference constants later, put brackets around the name: [constant\-name]
			#
			define \fIconstant\-name\fR=\fIvalue\fR
			\&.\&.\&.

			# Define branches by suffix DN, such as dc=example,dc=com;
			# ou=People,dc=example,dc=com; ou=Groups,dc=example,dc=com; and so on\&.
			# make\-ldif generates the necessary object class definitions and RDNs\&.
			#
			# A branch can have subordinateTemplates that define templates to use for
			# the branch entry\&.
			#
			# A branch can have additional attributes generated on the branch entry\&. See
			# the Description below for more information on specifying attribute values\&.
			#
			branch: \fIsuffix\-dn\fR
			[subordinateTemplate: \fItemplate\-name\fR:\fInumber\fR
			\&.\&.\&.]
			[\fIattribute\fR: \fIattr\-value\fR
			\&.\&.\&.]

			\&.\&.\&.

			# Define entries using templates\&.
			#
			# A template can extend another template\&.
			# A template defines the RDN attribute(s) used for generated entries\&.
			# A template can have a subordinateTemplate that defines a template to use for
			# the generated entries\&.
			#
			# A template then defines attributes\&. See the Description below for more
			# information on specifying attribute values\&.
			#
			template: \fItemplate\-name\fR
			[extends: \fItemplate\-name\fR]
			rdnAttr: \fIattribute\fR[+\fIattribute\fR \&.\&.\&.]
			[subordinateTemplate: \fItemplate\-name\fR:\fInumber\fR]
			[\fIattribute\fR: \fIattr\-value\fR
			\&.\&.\&.]

			\&.\&.\&.
			.fi
			.SH "DESCRIPTION"
			.PP
			Template files specify how to build LDIF\&. They allow you to define variables, insert random values from other files, and generally build arbitrarily large LDIF files for testing purposes\&. You pass template files to the
			\fBmake\-ldif\fR
			command when generating LDIF\&.
			.PP
			The Synopsis above shows the layout for a
			\fBmake\-ldif\fR
			template file\&. This section focuses on what you can do to specify entry attribute values, called
			\fIattr\-value\fR
			in the Synopsis section\&.
			.PP
			\fBSpecifying Attribute Values\fR
			.PP
			When specifying attribute values in
			\fBmake\-ldif\fR
			templates, you can use static text and constants that you have defined, enclosing names for constants in brackets,
			[myConstant]\&.
			.PP
			You can also use two kinds of tags when specifying attribute values\&. One kind of tag gets replaced with the value of another attribute in the generated entry\&. Such tags are delimited with braces,
			{ }\&. For example, if your template includes definitions for first name and last name attributes:
			.sp
			.if n \{\
			.RS 4
			.\}
			.nf
			givenName: <first>
			sn: <last>
			.fi
			.if n \{\
			.RE
			.\}
			.PP
			Then you can define a mail attribute that uses the values of both attributes, and an initials attribute that takes the first character of each\&.
			.sp
			.if n \{\
			.RS 4
			.\}
			.nf
			mail: {givenName}\&.{sn}@[myDomain]
			initials: {givenName:1}{sn:1}
			.fi
			.if n \{\
			.RE
			.\}
			.PP
			The other kind of tag is delimited with
			<
			and
			>, as shown above in the example with
			<first>
			and
			<last>\&. Tag names are not case sensitive\&. Many tags can take arguments separated by colons,
			:, from the tag names within the tag\&. OpenDJ supports the following tags\&.
			.PP
			<DN>
			.RS 4
			The DN tag gets replaced by the distinguished name of the current entry\&. An optional integer argument specifies the subcomponents of the DN to generate\&. For example, if the DN of the entry is
			uid=bjensen,ou=People,dc=example,dc=com
			<DN:1>
			gets replaced by
			uid=bjensen, and
			<DN:\-2>
			gets replaced by
			dc=example,dc=com\&.
			.RE
			.PP
			<File>
			.RS 4
			The File tag gets replaced by a line from a text file you specify\&. The File tag takes a required argument, the path to the text file, and an optional second argument, either
			random
			or
			sequential\&. For the file argument, either you specify an absolute path to the file such as
			<file:/path/to/myDescriptions>, or you specify a path relative to the
			/path/to/OpenDJ/config/MakeLDIF/
			directory such as
			<file:streets>\&. For the second argument, if you specify
			sequential
			then lines from the file are read in sequential order\&. Otherwise, lines from the file are read in random order\&.
			.RE
			.PP
			<First>
			.RS 4
			The first name tag gets replaced by a random line from
			/path/to/OpenDJ/config/MakeLDIF/first\&.names\&. Combinations of generated first and last names are unique, with integers appended to the name strings if not enough combinations are available\&.
			.RE
			.PP
			<GUID>
			.RS 4
			The GUID tag gets replaced by a 128\-bit, type 4 (random) universally unique identifier, such as
			f47ac10b\-58cc\-4372\-a567\-0e02b2c3d479\&.
			.RE
			.PP
			<IfAbsent>
			.RS 4
			The IfAbsent tag takes as its first argument the name of another attribute, and optionally as its second argument a value to use\&. This tag causes the attribute to be generated only if the named attribute is not present on the generated entry\&. Use this tag when you have used
			<Presence>
			to define another attribute that is not always present on generated entries\&.
			.RE
			.PP
			<IfPresent>
			.RS 4
			The IfPresent takes as its first argument the name of another attribute, and optionally as its second argument a value to use\&. This tag causes the attribute to be generated only if the named attribute is also present on the generated entry\&. Use this tag when you have used
			<Presence>
			to define another attribute that is sometimes present on generated entries\&.
			.RE
			.PP
			<Last>
			.RS 4
			The last name tag gets replaced by a random line from
			/path/to/OpenDJ/config/MakeLDIF/last\&.names\&. Combinations of generated first and last names are unique, with integers appended to the name strings if not enough combinations are available\&.
			.RE
			.PP
			<List>
			.RS 4
			The List tag gets replaced by one of the values from the list of arguments you provide\&. For example,
			<List:bronze:silver:gold>
			gets replaced with
			bronze,
			silver, or
			gold\&.
			.sp
			You can weight arguments to ensure some arguments are selected more often than others\&. For example, if you want two bronze for one silver and one gold, use
			<List:bronze;2:silver;1:gold;1>\&.
			.RE
			.PP
			<ParentDN>
			.RS 4
			The ParentDN tag gets replaced by the distinguished name of the parent entry\&. For example, if the DN of the entry is
			uid=bjensen,ou=People,dc=example,dc=com,
			<ParentDN>
			gets replaced by
			ou=People,dc=example,dc=com\&.
			.RE
			.PP
			<Presence>
			.RS 4
			The Presence tag takes a percent argument\&. It does not get replaced by a value itself, but instead results in the attribute being generated on the percentage of entries you specify in the argument\&. For example,
			description: <Presence:50>A description
			generates
			description: A description
			on half the entries\&.
			.RE
			.PP
			<Random>
			.RS 4
			The Random tag lets you generate a variety of random numbers and strings\&. The Random tag has the following subtypes, which you include as arguments, that is
			<Random:\fIsubtype\fR>\&.
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			alpha:\fIlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			alpha:\fIminlength\fR:\fImaxlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			numeric:\fIlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			numeric:\fIminvalue\fR:\fImaxvalue\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			numeric:\fIminvalue\fR:\fImaxvalue\fR:\fIformat\fR, where
			\fIformat\fR
			is a
			java\&.text\&.DecimalFormat
			pattern
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			alphanumeric:\fIlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			alphanumeric:\fIminlength\fR:\fImaxlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			chars:\fIcharacters\fR:\fIlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			chars:\fIcharacters\fR:\fIminlength\fR:\fImaxlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			hex:\fIlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			hex:\fIminlength\fR:\fImaxlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			base64:\fIlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			base64:\fIminlength\fR:\fImaxlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			month
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			month:\fImaxlength\fR
			.RE
			.sp
			.RS 4
			.ie n \{\
			\h'-04'\(bu\h'+03'\c
			.\}
			.el \{\
			.sp -1
			.IP \(bu 2.3
			.\}
			telephone, a telephone number starting with the country code
			+1
			.RE
			.RE
			.PP
			<RDN>
			.RS 4
			The RDN tag gets replaced with the RDN of the entry\&. Use this in the template after you have specified
			rdnAttr
			so that the RDN has already been generated when this tag is replaced\&.
			.sp
			An optional integer argument specifies the subcomponents of the RDN to generate\&.
			.RE
			.PP
			<Sequential>
			.RS 4
			The Sequential tag gets replaced by a sequentially increasing generated integer\&. The first optional integer argument specifies the starting number\&. The second optional boolean argument specifies whether to start over when generating entries for a new parent entry\&. For example,
			<Sequential>:42:true
			starts counting from 42, and starts over when the parent entry changes from
			o=Engineering
			to
			o=Marketing\&.
			.RE
			.PP
			<_DN>
			.RS 4
			The _DN tag gets replaced by the DN of the current entry with underscores in the place of commas\&.
			.RE
			.PP
			<_ParentDN>
			.RS 4
			The _ParentDN tag gets replaced by the DN the parent entry with underscores in the place of commas\&.
			.RE
			.SH "EXAMPLES"
			.PP
			The following example generates 10 organization units, each containing 50 entries\&.
			.sp
			.if n \{\
			.RS 4
			.\}
			.nf
			define suffix=dc=example,dc=com
			define maildomain=example\&.com
			define numusers=50
			define numorgs=10

			branch: [suffix]

			branch: ou=People,[suffix]
			subordinateTemplate: orgunit:[numorgs]
			description: This is the People container
			telephoneNumber: +33 00010002

			template: orgunit
			subordinateTemplate: person:[numusers]
			rdnAttr: ou
			ou: Org\-<sequential:0>
			objectClass: top
			objectClass: organizationalUnit
			description: This is the {ou} organizational unit

			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}\&.
			.fi
			.if n \{\
			.RE
			.\}
			.SH "SEE ALSO"
			.PP
			\m[blue]\fB\fBmake-ldif\fR(1)\fR\m[],
			/path/to/OpenDJ/config/MakeLDIF/example\&.template
			.SH "COPYRIGHT"
			.br
			Copyright \(co 2012 ForgeRock AS
			.br