Chapter 16   dbgen.pl


The dbgen.pl (database generator) tool is a Perl script that generates a sample database containing entries with random values. The output is LDIF (LDAP Data Interchange Format) text and can be loaded into a directory server and used to run performance tests.

As in the ldifgen tool (see Chapter 17), generated entries follow a fixed format, but dbgen.pl uses the standard schema and provides more realistic output. For these reasons, dbgen.pl is the recommended tool for random database creation.

This chapter contains the following sections:

• Command Usage

• Examples and Sample Output

Command Usage

---

The dbgen.pl tool generates a directory hierarchy that mimics a simple corporate structure. The script has an option for specifying a suffix , which will be the root of the generated hierarchy. By default it is dc=siroe,dc=com.

All of the leaf entries are inetOrgPerson objects by default, or you may specify the -O (the capital letter O) option to create all OrganizationalPerson objects. These object classes are used as templates, and the tool generates random values for their allowed attributes. See the "Examples and Sample Output" for examples of both object classes and the generated attribute values.

The tool also generates the root and organizational unit entries so that its output is a complete and valid LDAP directory hierarchy expressed in LDIF text. The organizational unit (ou) entries do not contain any attributes and are always the same. The root entry contains only simple aci attributes (Access Control Instructions), and these are also invariant.

The following diagram shows the directory tree representing the LDIF entries generated by the dbgen.pl tool.

Figure 16-1    LDAP Directory Tree Generated by dbgen.pl

The script relies on the following files in the installDir /data directory. You may edit the contents of these files to modify the output of the dbgen.pl tool (you will need root privileges to edit these files on UNIX systems):

• dbgen-OrgUnits - Contains the name of five organizational units. One entry for each organizational unit will be created under the suffix root of the generated directory. Then, each person entry will be randomly placed in one of the organizational units.

• dbgen-GivenNames and dbgen-FamilyNames - Contain over 8600 plausible first names and 13400 plausible surnames, respectively. Each entry representing a person is based on a given name and family name, each randomly chosen from these files. A sequential integer is also appended to all names to ensure that no two entries and no two DNs are identical.

Some attribute values such as email addresses are derived from the name and the suffix to create a plausible entry. Other data such as telephone numbers or titles are generated randomly or selected randomly from internal lists. These types of attribute values are not configurable.

---

Note

Due to the implementation of randomizing functions on certain platforms, the dbgen.pl tool may generate exactly the same attribute values every time it is invoked. While the values are seemingly random, they may in fact be identical to the other entries with the same DN created by different invocations of the command. Using the -r seed option will control this phenomenon. Using a different seed with every invocation, such as a timestamp, will ensure that output is always different. Note that invocations that use the same seed may produce the same output.

---

Syntax

The dbgen.pl tool has the following syntax:

dbgen.pl -o filename .ldif -n number [options ]

Where:

• filename .ldif is a writable file that will contain the LDIF output.

• number is the number of leaf entries that will be generated, in addition to the parent entries that are always present.

Running the dbgen.pl script without any options or parameters will display the usage help text that briefly describes all options.

The dbgen.pl script requires Perl version 5.005_03 or later. See "Where to Find Additional Information" for links to Perl resources.

If you customize the dbgen.pl script for added functionality, we encourage you to share your work with other LDAP users. Please post a message to the iplanet.server.idsrk public newsgroup with your ideas or your code.

Options

The dbgen.pl options and parameters are described in the following table.

Table 16-1    Command-Line Options for the dbgen.pl Tool 

Option	Parameter	Purpose
-o	outputFile	Specify the output file for the generated database. The output file is a complete directory hierarchy in LDIF text. This parameter is required.
-n	number	Specify the number of leaf entries in the generated database. This parameter is required.
-s	suffix	Specify the root of the generated hierarchy. The tool will create an entry of class top with a DN equal to the suffix , and the DN of all other generated entries will contain this suffix . The suffix must begin with either dc=DomainComponent or o=Organization . When this option is omitted, the default suffix is dc=siroe,dc=com.
-c		Use the cn (common name) attribute and value in the RDN. When this option is ommited, the uid attribte will be used.
-O	(capital letter O)	Generate all leaf entries as OrganizationalPerson objects and create only the corresponding attributes. When this option is omitted, all leaf entries will have the object class inetOrgPerson and the additional attributes of this class.
-r	seed	Specify a seed integer for the random number generator. The data generated by the tool will be different from one execution to the next only if the seed is different. A common way to ensure the seed is different with every execution is to use a timestamp.
-p		This option is mentioned in the online help, but it is deprecated.
-q		Quiet output mode: dbgen.pl will not display any measure of progress while running. When this flag is omitted, the tool will display a line of dots, one dot for every 10,000 entries generated.
-v		Verbose output mode: dbgen.pl will display additional messages about its progress.

Examples and Sample Output

---

The examples in this section show the output of the dbgen.pl tool. To save space, only the first full leaf entry is shown in each case. These examples use the default data files in the installDir /data directory.

InetOrgPerson Entries

This example demonstrates how the dbgen.pl script generates random attribute values for entries of the inetOrgPerson object class. It uses the date command of the UNIX shell to generate a seed for the random number generator. It also demonstrates the verbose output that includes progress messages.

$ perl dbgen.pl -o out1.ldif -n 3 -r `date +%S` -v

Loading Name Data...
Done
Ok, now generating 3 entries, please wait
.Generated 3 entries, 0 duplicates skipped

$ cat out1.ldif

dn: dc=siroe,dc=com
objectClass: top
objectClass: domain
dc: siroe
aci: (target=ldap:///dc=siroe,dc=com)(targetattr=*)
 (version 3.0; acl "acl1"; allow(write) userdn = "ldap:///self";)
aci: (target=ldap:///dc=siroe,dc=com)(targetattr=*)
 (version 3.0; acl "acl2"; allow(write) groupdn =
 "ldap:///cn=Directory Administrators, dc=siroe,dc=com";)
aci: (target=ldap:///dc=siroe,dc=com)(targetattr=*)
 (version 3.0; acl "acl3"; allow(read, search, compare) userdn =
 "ldap:///anyone";)

dn: ou=Accounting, dc=siroe,dc=com
objectClass: top
objectClass: organizationalUnit
ou: Accounting

dn: ou=Product Development, dc=siroe,dc=com
objectClass: top
objectClass: organizationalUnit
ou: Product Development

dn: ou=Product Testing, dc=siroe,dc=com
objectClass: top
objectClass: organizationalUnit
ou: Product Testing

dn: ou=Human Resources, dc=siroe,dc=com
objectClass: top
objectClass: organizationalUnit
ou: Human Resources

dn: ou=Payroll, dc=siroe,dc=com
objectClass: top
objectClass: organizationalUnit
ou: Payroll

dn: uid=HDiogo0, ou=Product Testing, dc=siroe,dc=com
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
cn: Harry Diogo
sn: Diogo
uid: HDiogo0
givenName: Harry
description: This is Harry Diogo0's description
userPassword: HDiogo0
departmentNumber: 5083
employeeType: Manager
homePhone: +1 804 339-8183
initials: H. D.
telephoneNumber: +1 818 605-3216
facsimileTelephoneNumber: +1 206 768-6857
mobile: +1 408 194-1108
pager: +1 415 692-3053
manager: Pippy Mejdal0
secretary: Eden Yvon0
roomNumber: 2265
carLicense: ORHYA5I
l: Redwood Shores
ou: Product Testing
mail: Harry_Diogo@siroe.com
postalAddress: Product Testing Dept #441, Room#73
title: Senior Product Testing Guru

dn: uid=MPlanta1, ou=Product Development, dc=siroe,dc=com
[...]

dn: uid=GVela2, ou=Human Resources, dc=siroe,dc=com
[...]

OrganizationalPerson Entries

In this example we use the -O (capital letter O) option to generate entries of the organizationalPerson object class. We also use the -c and -s options to customize the DN of the generated entries.

$ perl dbgen.pl -o out2.ldif -n 3 -O -r `date +%S` -q \
                -c -s "o=Varrius Corp.,c=US"

$ cat out2.ldif
dn: o=Varrius Corp.,c=US
objectClass: top
objectClass: organization
o: Varrius Corp.
aci: (target=ldap:///o=Varrius Corp.,c=US)(targetattr=*)
 (version 3.0; acl "acl1"; allow(write) userdn = "ldap:///self";)
aci: (target=ldap:///o=Varrius Corp.,c=US)(targetattr=*)
 (version 3.0; acl "acl2"; allow(write) groupdn =
 "ldap:///cn=Directory Administrators, o=Varrius Corp.,c=US";)
aci: (target=ldap:///o=Varrius Corp.,c=US)(targetattr=*)
 (version 3.0; acl "acl3"; allow(read, search, compare) userdn =
 "ldap:///anyone";)

dn: ou=Accounting, o=Varrius Corp.,c=US
objectClass: top
objectClass: organizationalUnit
ou: Accounting

dn: ou=Product Development, o=Varrius Corp.,c=US
objectClass: top
objectClass: organizationalUnit
ou: Product Development

dn: ou=Product Testing, o=Varrius Corp.,c=US
objectClass: top
objectClass: organizationalUnit
ou: Product Testing

dn: ou=Human Resources, o=Varrius Corp.,c=US
objectClass: top
objectClass: organizationalUnit
ou: Human Resources

dn: ou=Payroll, o=Varrius Corp.,c=US
objectClass: top
objectClass: organizationalUnit
ou: Payroll

dn: cn=Mihaela Inman, ou=Accounting, o=Varrius Corp.,c=US
objectClass: top
objectClass: person
objectClass: organizationalPerson
cn: Mihaela Inman
sn: Inman
uid: MInman0
givenName: Mihaela
description: This is Mihaela Inman's description
userPassword: MInman0
telephoneNumber: +1 714 803-8455
facsimileTelephoneNumber: +1 714 371-9310
l: Santa Clara
ou: Accounting
mail: Mihaela_Inman@siroe.com
postalAddress: Accounting Dept #339, Room#98
title: Chief Accounting Director

dn: cn=Randall Braddy,ou=Human Resources,o=Varrius Corp.,c=US
[...]

dn: cn=Morley Cantwell,ou=Product Development,o=Varrius Corp.,c=US
[...]