9.4. Perl Scripts

This section describes the following Perl scripts:

9.4.1. bak2db.pl (Restores a Database from Backup)

Restores a database from a backup.
Syntax

bak2db.pl -D rootdn -w password | -w - | -j filename -a backupDirectory [ -t databaseType ] [ -n backend ]

Options

The script bak2db.pl creates an entry in the directory that launches this dynamic task. The entry is generated based upon the values provided for each option.

Table 9.20. bak2db.pl Options

Option Description
-a backupDirectory The directory of the backup files.
-D rootdn Gives the user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config.
-j filename The name of the file containing the password.
-n backendInstance Specifies the back end name, such as userRoot, which is being restored. This option is only used for filesystem replica initialization or to restore a single database; it is not necessary to use the -n option to restore the entire directory.
-t databaseType The database type. The only possible database type is ldbm.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

9.4.2. cl-dump.pl (Dumps and Decodes the Changelog)

Troubleshoots replication-related problems.

Note

cl-dump.pl is in the /usr/bin directory.
Syntax

cl-dump.pl [ -h host ] [ -p port ] [ -D bindDn ] [ -w bindPassword | -P bindCert ] [ -r replicaRoots ] [ -o outputFile ] [ -c ]

cl-dump.pl -i changelogFile [ -o outputFile ] [ -c ]

Options

Without the -i option, the script must be run when the Directory Server is running from a location from which the server's changelog directory is accessible.

Table 9.21. cl-dump.pl command options

Option Description
-c Dumps and interprets change sequence numbers (CSN) only. This option can be used with or without the -i option.
-D bindDn Specifies the Directory Server's bind DN. Defaults to cn=Directory Manager if the option is omitted.
-h host Specifies the Directory Server's host. Defaults to the server where the script is running.
-i changelogFile Specifies the path to the changelog file. If there is a changelog file and if certain changes in that file are base-64 encoded, use this option to decode that changelog.
-o outputFile Specifies the path, including the filename, for the final result. Defaults to STDOUT if omitted.
-p port Specifies the Directory Server's port. The default value is 389.
-P bindCert Specifies the path, including the filename, to the certificate database that contains the certificate used for binding.
-r replicaRoots Specifies the replica-roots whose changelog to dump. When specifying multiple roots, use commas to separate roots. If the option is omitted, all the replica roots will be dumped.
-w bindPassword Specifies the password for the bind DN.

9.4.3. db2bak.pl (Creates a Backup of a Database)

Creates a backup of the database. This Perl script can only be executed when the server is running.
Syntax

db2bak.pl -D rootdn -w password | -w - | -j filename [ -a dirName ] [ -t db_type ]

Options

The script db2bak.pl creates an entry in the directory that launches this dynamic task. The entry is generated based upon the values provided for each option. Currently, the only possible database type is ldbm.

Table 9.22. db2bak.pl Options

Option Description
-a dirName The directory where the backup files will be stored. The /var/lib/dirsrv/slapd-instance_name/bak directory is used by default. The backup file is named according to the year-month-day-hour format (YYYY_MM_DD_hhmmss).
-D rootdn The user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config.
-j filename The name of the file containing the password.
-t The database type. Currently, the only possible database type is ldbm.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

9.4.4. db2index.pl (Creates and Generates Indexes)

Creates and generates the new set of indexes to be maintained following the modification of indexing entries in the cn=config configuration file.

Note

db2index uses the entryrdn index to order the parent-child entries when it indexes the database to preserve the proper hierarchy of parent and child entries. If the entryrdn index is unavailable for some reason, then db2index uses the parentid key for each entry to identify the parent. This second method allows the index operation to succeed, but the operation may take a long time to complete.
Syntax

db2index.pl -D rootdn -w password | -w - | -j filename -n backendInstance [ -t attributeName(:indextypes(:mathingrules)) ] [ -T vlvAttributeName ]

Options

The script db2index.pl creates an entry in the directory that launches this dynamic task. The entry is generated based upon the values provided for each option.

Table 9.23. db2index.pl Options

Option Description
-D rootdn Gives the user DN with root permissions, such as Directory Manager.
-j filename The name of the file containing the password.
-n backendInstance Gives the instance to be indexed. If the instance is not specified, the script reindexes all instances.
-t attributeName{:indextypes(:mathingrules)} Gives the name of the attribute to be indexed. If omitted, all the indexes defined for the specified instance are generated. Optionally, this can include the index type (eq, pres, sub, approx) and a matching rule OID.
-T vlvAttributeName Gives the names of the VLV attributes to be reindexed. The name is the VLV index object's common name in cn=config.
-w password Gives the password associated with the user DN.
-w - Prompts for the password associated with the user DN.

9.4.5. db2ldif.pl (Exports Database Contents to LDIF)

Exports the contents of the database to LDIF. This script creates an entry in the directory that launches this dynamic task. The entry is generated based upon the values provided for each option. Ellipses indicate that multiple occurrences are allowed.

Note

db2ldif.pl uses the entryrdn index to order the parent-child entries when it exports the database; this enables the exported LDIF file to be used for import, since the proper hierarchy of parent and child entries is preserved. If the entryrdn index is unavailable for some reason, then db2ldif.pl uses the parentid key for each entry to identify the parent and export it before the child entry. This second method allows the export operation to succeed, but the operation may take a long time to complete.
Syntax

db2ldif.pl -D rootdn -w password | -w - | -j filename -n backendInstance | -s includeSuffix ... [ -x excludeSuffix ... ] [ -a outputFile ] [ -N ] [ -r ] [ -C ] [ -u ] [ -U ] [ -m ] [ -E ] [ -1 ] [ M ]

Options

To run this script, the server must be running, and either the -n or -s option is required.

Table 9.24. db2ldif.pl Options

Option Description
-1 Deletes, for reasons of backward compatibility, the first line of the LDIF file that gives the version of the LDIF standard.
-a outputFile Gives the filename of the output LDIF file.
-C Uses only the main database file.
-D rootdn Gives the user DN with root permissions, such as Directory Manager.
-E Decrypts encrypted data during export. This option is used only if database encryption is enabled.
-j filename The name of the file containing the password.
-m Sets minimal base-64 encoding.
-M Uses multiple files for storing the output LDIF, with each instance stored in instance filename (where filename is the filename specified for -a option).
-n backendInstance Gives the instance to be exported.
-N Suppresses printing sequential numbers.
-r
Exports the information required to initialize a replica when the LDIF is imported.
The LDIF file which is created with db2ldif.pl can be imported using ldif2db.pl. When it is imported, if the -r option was used, than the database is automatically initialized as a replica.
See Section 9.4.8, “ldif2db.pl (Import)” for information on importing an LDIF file.
-s includeSuffix Gives suffixes to be included or the subtrees to be included if -n has been used.
-u Requests that the unique ID is not exported.
-U Requests that the output LDIF is not folded.
-w password Gives the password associated with the user DN.
-w - Prompts for the password associated with the user DN.
-x excludeSuffix Gives suffixes to be excluded.

9.4.6. fixup-linkedattrs.pl (Regenerate Linked and Managed Attributes)

The Directory Server has a Linked Attributes Plug-in which allows one attribute, set in one entry, to update another attribute in another entry automatically. Both entries have DNs for values. The DN value in the first entry points to the entry for the plug-in to update; the attribute in the second entry contains a DN back-pointer to the first entry.
The fixup-linkedattrs.pl script creates the managed attributes in the user entries once the linking plug-in instance is created or updates the managed attributes to keep everything in sync after operations like replication or synchronization.
To run this script, the server must be running. The script creates an entry in the directory that launches this dynamic task.
Syntax

fixup-linkedattrs.pl -D rootdn -w password | -w - | -j filename [ -l DN ]

Options

 

Table 9.25. fixup-linkedattrs.pl Options

Option Description
-D rootdn Gives the user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config.
-j filename The name of the file containing the password.
-l DN Gives the target DN for which to update the linked attributes. If this is not set, then the default is to update all linked and managed attributes for the entire subtree or directory tree.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

9.4.7. fixup-memberof.pl (Regenerate memberOf Attributes)

Regenerates and updates memberOf on user entries to coordinate changes in group membership.
To run this script, the server must be running. The script creates an entry in the directory that launches this dynamic task.
Syntax

fixup-memberof.pl -D rootdn -w password | -w - | -j filename -b baseDN [ -f filter ]

Options

 

Table 9.26. fixup-memberof.pl Options

Option Description
-b baseDN The DN of the subtree containing the entries to update.
-D rootdn Gives the user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config.
-f filter An LDAP query filter to use to select the entries within the subtree to update. If there is no filter set, then the default filter is objectclass=inetorgperson, and every entry belonging to that object class within the subtree is updated.
-j filename The name of the file containing the password.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

9.4.8. ldif2db.pl (Import)

To run this script, the server must be running. The script creates an entry in the directory that launches this dynamic task. The entry is generated based upon the values provided for each option. Ellipses indicate that multiple occurrences are allowed.
Syntax

ldif2db.pl -D rootdn -w password | -w - | -j filename -n backendInstance | -s includeSuffix [ -x excludeSuffix ] [ -O ] [ -c ] [ -g string ] [ -G namespaceId ] [ -i filename ] [ -E ]

Options

 

Table 9.27. ldif2db.pl Options

Option Description
-c Merges chunk size.
-D rootdn Specifies the user DN with root permissions, such as Directory Manager.
-E Decrypts encrypted data during export. This option is used only if database encryption is enabled.
-g string
Generates a unique ID. Type none for no unique ID to be generated and deterministic for the generated unique ID to be name-based. By default, a time-based unique ID is generated.
When using the deterministic generation to have a name-based unique ID, it is also possible to specify the namespace for the server to use, as follows: 
-g deterministic namespaceId
namespaceId is a string of characters in the format 00-xxxxxxxx-xxxxxxxx-xxxxxxxx-xxxxxxxx.
Use this option to import the same LDIF file into two different Directory Servers and the contents of both directories should have the same set of unique IDs. If unique IDs already exist in the LDIF file being imported, then the existing IDs are imported to the server, regardless of the options specified.
-G namespaceId Generates a namespace ID as a name-based unique ID. This is the same as specifying the -g deterministic option.
-i filename Specifies the filename of the input LDIF files. When multiple files are imported, they are imported in the order they are specified on the command line.
-j filename Specifies the path, including the filename, to the file that contains the password associated with the user DN.
-n backendInstance Specifies the instance to be imported.
-O Requests that only the core database is created without attribute indexes.
-s includeSuffix Specifies the suffixes to be included or specifies the subtrees to be included if -n has been used.
-w password Specifies the password associated with the user DN.
-w - Prompts for the password associated with the user DN.
-x excludeSuffix Specifies the suffixes to be excluded.

9.4.9. logconv.pl (Log Converter)

Analyzes the access logs of a Directory Server to extract usage statistics and count the occurrences of significant events. It is compatible with log formats from previous releases of Directory Server. For information on access logs, see Section 7.1, “Access Log Reference”.

Note

logconv.pl is in the /usr/bin directory.
The tool will extract the following information from access logs:

Table 9.28. Information Extracted from Access Logs

  • Number of restarts
  • Total number of connections
  • Total operations requested
  • Total results returned
  • Results to requests ratio
  • Number of searches
  • Number of modifications
  • Number of adds
  • Number of deletes
  • Performance statistics of searches
  • Performance statistics of modifications
  • Performance statistics of adds
  • Performance statistics of deletes
  • Number of modified RDNs
  • Persistent searches
  • Internal operations (with verbose logs)
  • Entry operations (with verbose logs)
  • Extended operations
  • Abandoned requests
  • Smart referrals received (verbose logs)
  • VLV (virtual list view) operations
  • VLV unindexed searches
  • Server-side sorting operations
  • SSL connections
  • Performance lowering operations:
  • Entire database searches
  • Unindexed searches (details optional)
  • FDs (file descriptors) taken
  • FDs returned
  • Highest FD taken
  • Disruptions:
  • Broken pipes
  • Connections reset by peer
  • Unavailable resources (and detail)
  • Total binds and types of binds
  • Most frequent occurrence lists (optional)
  • Error and return codes
  • Failed logins
  • Connection codes
  • Client IP addresses and connection codes
  • Bind DNs
  • Base DNs for searching
  • Search filters
  • Etimes (elapsed operation time)
  • Longest etimes
  • Nentries (number of entries in result)
  • Largest Nentries
  • Extended operations
  • Most requested attributes
  • Recommendations (optional)
The logconv.pl tool displays two types of statistics useful for monitoring and optimizing directory usage:
  • Simple counts of events such as the total number of binds, connections separated by SSL and TLS protocol versions, and the number of searches provide overall usage information. This is the basic information that the tool will always print.
  • Lists of the most frequently occurring parameters in LDAP requests provide insight into how the directory information is being accessed. For example, lists of the top ten bind DNs, base DNs, filter strings, and attributes returned can help administrators optimize the directory for its users. These lists are optional because they are computation intensive: specify only the command-line options required (see Options).
Some information that is extracted by the logconv.pl script is available only in logs from current releases of Directory Server; the corresponding values will be zero when analyzing logs from older versions. In addition, some information will only be present in the logs if verbose logging is enabled in the Directory Server. For more information, see Section 3.1.1.2, “nsslapd-accesslog-level (Access Log Level)”.
The following issues will affect the output and performance of this tool:
  • Some data extracted from logs depend on connection and operation numbers that are reset and no longer unique after a server restarts. Therefore, to obtain the most accurate counts, the logs to be analyzed should not span the restart of the Directory Server.
  • Due to changes in access log format in current releases of Directory Server that affected operation numbers, the tool will be more accurate logs from current versions when processing large amounts of access logs.
  • For performance reasons, it is not recommended to run more than one gigabyte of access logs through the script at any one time.
Syntax

logconv.pl [ -S startTimestamp ] [ -E endTimestamp ] [ -d mgrDN ] [ -D tmp_directory ] [ -X ipAddress ] [ -m ] [ -M ] [ -h ] [ -s size_limit ] [ -V ] [ -efcibaltnxgjuyp ] [ accessLog ]

Options

Table 9.29, “logconv.pl Options” describes the logconv.pl command-line options.

Table 9.29. logconv.pl Options

Option Description
-d mgrDN Specifies the distinguished name (DN) of the Directory Manger in the logs being analyzed. This allows the tool to collect statistics for this special user. The mgrDN parameter should be given in double quotes ("") for the shell. When this parameter is omitted, logconv.pl will use the default manager DN of the Directory Server, "cn=Directory Manager".
-D tmp_directory Sets the location of the directory to store temporary data. The default is /tmp. For performance improvements, you can set this path to a RAM disk.
-E endTimestamp Specifies the end timestamp; the timestamp must follow the exact format as specified in the access log.
-h Displays the usage help text that briefly describes all options.
-M Charts per-minute statistics for access within the specified time period. This is useful for charting peaks and troughs in usage patterns.
-m Charts per-second statistics for access within the specified time period. This is useful for charting peaks and troughs in usage patterns.
-s number Specifies the number of items in each of the list options below. The default is 20 when this parameter is omitted. For example, -s 10 -i will list the ten client machines that access the Directory Server most often. This parameter will apply to all lists that are enabled, and it will have no effect if none are displayed.
-S startTimestamp Specifies the start timestamp; the timestamp must follow the exact format as specified in the access log.
-V Enables verbose output. With this option, logconv.pl will compute and display all of the optional lists described in Table 9.30, “logconv.pl Options to Display Occurrences”
-X ipAddress Specifies the IP address of a client to exclude from the statistics. This client will not appear in lists of IP addresses (the i flag), and the connection codes it generates will not be tallied in the total connections (default statistic) nor in the connection code details (the c flag). For example, an administrator may want the server to ignore the effect of a load balancer that connects to the Directory Server at regular intervals. This option may be repeated to exclude multiple IP addresses.
accessLog The name of a file that contains the access log of the Directory Server. You can specify multiple files or use wildcard characters. Additionally, the logconv.pl scripts supports compressed files and tar archives based on the file extension, such as .bz2 or .tar.gz. The statistics are computed over the set of all logs, so all logs should pertain to the same Directory Server. The tool ignores any file with the name access.rotationinfo.
Table 9.30, “logconv.pl Options to Display Occurrences” describes the options that enable the optional lists of occurrences. Specify only those required; specifying a large number of options can produce excessive output and affect execution speed. These parameters can be specified in any number and in any order, but they must all be given together as a single option on the command line, such as -abcefg.
The lists are always output in the order in which they appear in the following table, regardless of the order in which they are given on the command line.

Table 9.30. logconv.pl Options to Display Occurrences

Option Description
e Lists the most frequent error and return codes.
f Lists the bind DNs with the most failed logins (invalid password).
c Lists the number of occurrences for each type of connection code.
i Lists the IP addresses and connection codes of the clients with the most connections, which detects clients that may be trying to compromise security.
b Lists the most frequently used bind DNs.
a Lists the most frequent base DNs when performing operations.
l Lists the most frequently used filter strings for searches.
t Lists the longest and most frequent etimes (elapsed operation time).
n Lists the largest and most frequent nentries (entries per result).
x Lists the number and OID of all extended operations.
r Lists the names of the most requested attributes.
g Lists the details of all abandoned operations.
j Gives recommendations based on data collected from the log file.
u Gives operation details about unindexed searches.
y Lists connection latency details, which indicates the overall connection latency.
p Lists open connection ID statistics, which indicates the FDs that are not yet closed.

9.4.10. migrate-ds.pl

Warning

There is no direct migration path from Red Hat Directory Server 7.1 to Red Hat Directory Server 9.0, but it is possible to migrate the data by migrating 7.1 to 8.2, and then migrating 8.2 to 9.0.
An 8.2 migration procedure, using this script, is described in the migration chapter of the Directory Server Installation Guide.
It is possible to use this script to migrate directly from 7.1 to 9.0. However, this migration path is not fully supported. Please contact Red Hat Support Services before attempting to perform a direct 7.1 to 9.0 migration.
The migrate-ds.pl script is used to migrate a Directory Server 7.1 instance. Migration can happen between instances on on the same machine, on different machines, or on different platforms. This script only migrates a Directory Server instance, not an Admin Server.
Do not run setup-ds-admin.pl for the Directory Server 8.2 instance before running the migration script if you are migrating from a 7.1 server.
Information can be passed with the script or in an .inf file, same as the setup scripts. Both the .inf parameters and command-line arguments are described in the silent configuration section of the Installation Guide.
Syntax

migrate-ds.pl --oldsroot=server_directory [ --actualsroot=server_directory ] [ --instance=instance_name ] [ --file=name ] [ --cross ] [ --debug ] [ --log=name ] General.ConfigDirectoryAdminPwd=password

Options

 

Option Alternate Options Description
General.ConfigDirectoryAdminPwd=password   Required. This is the password for the configuration directory administrator of the old Directory Server (the default user name is admin).
--oldsroot -o Required. This is the path to the server root directory in the old 7.1 Directory Server installation. The default path in 7.1 servers is /opt/redhat-ds/.
--actualsroot -a This is used for migrating between two machines to specify the real path to the current server root directory in the old 7.1 Directory Server installation if that directory is mounted on a networked drive or tarballed and moved to a relative directory. In that case, the oldsroot parameter sets the directory from which the migration is run (such as machine_new:/migrate/opt/redhat-ds/), while the actualsroot parameter sets the server root, (/opt/redhat-ds/).
--instance -i This parameter specifies a specific instance to migrate. This parameter can be used multiple time to migrate several instances simultaneously. By default, the migration script migrates all Directory Server instances on the machine.
--file=name -f name This sets the path and name of the .inf file provided with the migration script. The only parameter is the General.ConfigDirectoryAdminPwd parameter, which is the configuration directory administrator's password. Any other configuration setting is ignored by the migration script.
--cross -c or -x This parameter is used when the Directory Server is being migrated from one machine to another with a different architecture. For cross-platform migrations, only certain data are migrated. This migration action takes database information exported to LDIF and imports into the 8.2 databases. Changelog information is not migrated. If a supplier or hub is migrated, then all its replicas must be reinitialized.
--debug -d[dddd] This parameter turns on debugging information. For the -d flag, increasing the number of d's increases the debug level.
--logfile name -l
This parameter specifies a log file to which to write the output. If this is not set, then the migration information is written to a temporary file, named /tmp/migrateXXXXX.log.
To disable logging, set /dev/null as the logfile.

9.4.11. migrate-ds-admin.pl

Warning

There is no direct migration path from Red Hat Directory Server 7.1 to Red Hat Directory Server 9.0, but it is possible to migrate the data by migrating 7.1 to 8.2, and then migrating 8.2 to 9.0.
An 8.2 migration procedure, using this script, is described in the Directory Server Installation Guide.
It is possible to use this script to migrate directly from 7.1 to 9.0. However, this migration path is not fully supported. Please contact Red Hat Support Services before attempting to perform a direct 7.1 to 9.0 migration.
The migrate-ds-admin.pl script is used to migrate a Directory Server 7.1 instance. Migration can happen between instances on on the same machine, on different machines, or on different platforms. This script migrates both the Directory Server instances and the Admin Server for the 7.1 deployment.
Do not run setup-ds-admin.pl for the Directory Server 8.2 instance before running the migration script if you are migrating from a 7.1 server.
Information can be passed with the script or in an .inf file, same as the setup scripts. Both the .inf parameters and command-line arguments are described in the silent configuration section of the Installation Guide.
Syntax

migrate-ds-admin.pl --oldsroot=server_directory [ --actualsroot=server_directory ] [ --instance=instance_name ] [ --file=name ] [ --cross ] [ --debug ] [ --log=name ] General.ConfigDirectoryAdminPwd=password

Options

 

Option Alternate Options Description
General.ConfigDirectoryAdminPwd=password   Required. This is the password for the configuration directory administrator of the old Directory Server (the default user name is admin).
--oldsroot -o Required. This is the path to the server root directory in the old 7.1 Directory Server installation. The default path in 7.1 servers is /opt/redhat-ds/.
--actualsroot -a This is used for migrating between two machines to specify the real path to the current server root directory in the old 7.1 Directory Server installation if that directory is mounted on a networked drive or tarballed and moved to a relative directory. In that case, the oldsroot parameter sets the directory from which the migration is run (such as machine_new:/migrate/opt/redhat-ds/), while the actualsroot parameter sets the server root, (/opt/redhat-ds/).
--instance -i This parameter specifies a specific instance to migrate. This parameter can be used multiple time to migrate several instances simultaneously. By default, the migration script migrates all Directory Server instances on the machine.
--file=name -f name This sets the path and name of the .inf file provided with the migration script. The only parameter is the General.ConfigDirectoryAdminPwd parameter, which is the configuration directory administrator's password. Any other configuration setting is ignored by the migration script.
--cross -c or -x This parameter is used when the Directory Server is being migrated from one machine to another with a different architecture. For cross-platform migrations, only certain data are migrated. This migration action takes database information exported to LDIF and imports into the 8.2 databases. Changelog information is not migrated. If a supplier or hub is migrated, then all its replicas must be reinitialized.
--debug -d[dddd] This parameter turns on debugging information. For the -d flag, increasing the number of d's increases the debug level.
--logfile name -l
This parameter specifies a log file to which to write the output. If this is not set, then the migration information is written to a temporary file, named /tmp/migrateXXXXX.log.
To disable logging, set /dev/null as the logfile.

9.4.12. ns-accountstatus.pl (Establishes Account Status)

Provides account status information to establish whether an entry or group of entries is inactivated.
Syntax

ns-accountstatus.pl [ -D rootdn ] [ -w password | -w - | -j filename ] [ -p port ] [ -h host ] -I DN [ -? ]

Options

Table 9.31. ns-accountstatus.pl Options

Option Description
-D rootdn Specifies the Directory Server user DN with root permissions, such as Directory Manager.
-h host Specifies the host name of the Directory Server. The default value is the full host name of the machine where Directory Server is installed.
-I DN Specifies the entry DN or role DN whose status is required.
-j filename Specifies the path, including the filename, to the file that contains the password associated with the user DN.
-p port Specifies the Directory Server's port. The default value is the LDAP port of Directory Server specified at installation time.
-w password Specifies the password associated with the user DN.
-w - Prompts for the password associated with the user DN.
-? Opens the help page.

9.4.13. ns-activate.pl (Activates an Entry or Group of Entries)

Activates an entry or group of entries.
Syntax

ns-activate.pl [ -D rootdn ] [ -w password | -w - | -j filename ] [ -p port ] [ -h host ] -I DN [ -? ]

Options

Table 9.32. ns-activate.pl Options

Option Description
-D rootdn Specifies the Directory Server user DN with root permissions, such as Directory Manager.
-h host Specifies the host name of the Directory Server. The default value is the full host name of the machine where Directory Server is installed.
-I DN Specifies the entry DN or role DN to activate.
-j filename Specifies the path, including the filename, to the file that contains the password associated with the user DN.
-p port Specifies the Directory Server's port. The default value is the LDAP port of Directory Server specified at installation time.
-w password Specifies the password associated with the user DN.
-w - Prompts for the password associated with the user DN.
-? Opens the help page.

9.4.14. ns-inactivate.pl (Inactivates an Entry or Group of Entries)

Inactivates, and consequently locks, an entry or group of entries.
Syntax

ns-inactivate.pl [ -D rootdn ] [ -w password | -w - | -j filename ] [ -p port ] [ -h host ] -I DN [ -? ]

Options

Table 9.33. ns-inactivate.pl Options

Option Description
-D rootdn Specifies the Directory Server user DN with root permissions, such as Directory Manager.
-h host Specifies the host name of the Directory Server. The default value is the full host name of the machine where Directory Server is installed.
-I DN Specifies the entry DN or role DN to deactivate.
-j filename Specifies the path, including the filename, to the file that contains the password associated with the user DN.
-p port Specifies the Directory Server's port. The default value is the LDAP port of Directory Server specified at installation time.
-w password Specifies the password associated with the user DN.
-w - Prompts for the password associated with the user DN.
-? Opens the help page.

9.4.15. ns-newpwpolicy.pl (Adds Attributes for Fine-Grained Password Policy)

Adds entries required for implementing the user- and subtree-level password policy. For instructions on how to enable this feature, see the Red Hat Directory Server Administrator's Guide.
Syntax

ns-newpwpolicy.pl [ -D rootdn ] [ -w password | -j filename ] [ -p port ] [ -h host ] -U userDN -S suffixDN [ -? ]

Options

Table 9.34. ns-newpwdpolicy.pl Options

Option Description
-D rootdn Specifies the Directory Server user DN with root permissions, such as Directory Manager. The default value is cn=directory manager.
-h host Specifies the host name of the Directory Server. The default value is localhost or the full host name of the machine where Directory Server is installed.
-j filename Specifies the path, including the filename, to the file that contains the password associated with the user DN.
-p port Specifies the Directory Server's port. The default value is 389 or the LDAP port of Directory Server specified at installation time.
-S suffixDN Specifies the DN of the suffix entry that needs to be updated with subtree-level password policy attributes.
-U userDN Specifies the DN of the user entry that needs to be updated with user-level password policy attributes.
-w password Specifies the password associated with the user DN.
-? Opens the help page.

9.4.16. register-ds-admin.pl

The register-ds-admin.pl script can be used for two things:
  • Registering an existing Directory Server instance with a different Admin Server or Configuration Directory Server.
  • Creating a new, local Admin Server when only a Directory Server was installed previously.

Important

The register-ds-admin.pl script does not support external LDAP URLs, so the Directory Server instance must be registered against a local Admin Server.
Syntax

register-ds-admin.pl.pl [ --debug ] [ --log=name ]

Options

 

Option Alternate Options Description
--debug -d[dddd] This parameter turns on debugging information. For the -d flag, increasing the number of d's increases the debug level.
--logfile name -l This parameter specifies a log file to which to write the output. If this is not set, then the setup information is written to a temporary file. To not use a log file, set the file name to /dev/null.

9.4.17. remove-ds.pl

The remove-ds.pl script removes a single instance of Directory Server. The server instance usually must be running when this script is run so that the script can bind to the instance. It is also possible to force the script to run, which may be necessary if there was an interrupted installation process or the instance is corrupted or broken so that it cannot run.
When the instance is removed, it is shutdown and all of its configuration files are removed. Certificate database files, like cert8.db and key3.db, are not removed, so the remaining instance directory is renamed slapd-instance.removed.
Syntax

remove-ds.pl [ -f ] -i instance_name [ -a ]

Options

 

Option Parameter Description
-a   Removes the certificate database files and the backup directory of the configuration files (slapd-instance.removed) as part of the removal procedure.
-f Forces the removal of the instance. This can be useful if the instance is not running but must be removed anyway.
-i instance_name The name of the instance to remove.

9.4.18. remove-ds-admin.pl

The remove-ds-admin.pl script removes every instance of Directory Server on a system and the associated Admin Server. The server instances usually must be running when this script is run so that the script can bind to the instances.
It is also possible to force the script to run, which may be necessary if there was an interrupted installation process or the instance is corrupted or broken so that it cannot run.
Directory Server Removal Information

When a Directory Server instance is removed, it is shut down and all of its configuration files are removed.

By default, the certificate database files, like cert8.db and key3.db, are not removed. The remaining Directory Server instance directory (containing the security databases) is renamed slapd-instance.removed. Using the -a option with the script removes the security databases as well.
Admin Server Removal Information

When an Admin Server instance is removed, it is shut down and most of its configuration files are removed.

The nss.conf file for the Admin Server instance is preserved in an archvied instance directory.
By default, the certificate database files, like cert8.db and key3.db, are not removed and are preserved in an archived instance directory. Using the -a option with the script removes the security databases for the Admin Server (as well as the Directory Server).
Syntax

remove-ds-admin.pl -y [ -f ] [ -a ]

Options

 

Option Description
-a Removes the certificate database files as part of the removal procedure and reverts the configuration files back to their initial state.
-f Forces the removal of the instance. This can be useful if the instance is not running but must be removed anyway.
-y Performs the removal operation. This is required; otherwise, the script essential performs a dry-run and does not remove any Admin Server or Directory Server instances.

9.4.19. repl-monitor.pl (Monitors Replication Status)

Shows in-progress status of replication.

Note

repl-monitor.pl is in the /usr/bin directory.
Syntax

repl-monitor.pl [ -h host ] [ -p port ] [ -f configFile ] [ -u refreshUrl ] [ -t refreshInterval ] [ -r ]

Options

Table 9.35. repl-monitor.pl Options

Option Description
-f configFile Specifies the absolute path to the configuration file, which defines the connection parameters used to connect to LDAP servers to get replication information. For more information about the configuration file, see Configuration File Format.
-h host Specifies the initial replication supplier's host. The default value is the current host name.
-p port Specifies the initial replication supplier's port. The default value is 389.
-r If specified, causes the routine to be entered without printing the HTML header information. This is suitable when making multiple calls to this routine — such as specifying multiple, different, unrelated supplier servers — and expecting a single HTML output.
-t refreshInterval Specifies the refresh interval in seconds. The default value is 300 seconds. This option must be used with the -u option.
-u refreshUrl Specifies the refresh URL. The output HTML file may invoke a CGI program periodically. If this CGI program in turn calls this script, the effect is that the output HTML file would automatically refresh itself. This is useful for continuous monitoring. See also the -t option. The script has been integrated into Red Hat Administration Express, so that the replication status can be monitored through a web browser.

Configuration File Format

The configuration file defines the following:

  • The connection parameters for connecting to the LDAP servers to get replication information; specifying this information is mandatory.
  • The server alias for more readable server names; specifying this information is optional.
  • The color thresholds for time lags; specifying this information is optional.
The format for the configuration file is shown below. 
[connection]
host:port:binddn:bindpwd:bindcert
host:port:binddn:bindpwd:bindcert
...

[alias]
alias = host:port
alias = host:port
...

[color]
lowmark = color
lowmark = color
The connection section defines how this tool may connect to each LDAP server in the replication topology to get the replication-agreement information. The default binddn is cn=Directory Manager. Simple bind will be used unless bindcert is specified with the path of a certificate database.
A server may have a dedicated or shared entry in the connection section. The script will find out the most matched entry for a given server. For example, if all the LDAP servers except host1 share the same binddn and bindpassword, the connection section will need to contain just two entries: 
[connection]
*:*:binddn:bindpassword:
host1:*:binddn1:bindpassword1:
In the optional alias section, use aliases such as Supplier1, Supplier2, and Hub1, to identify the servers in the replication topology. If used, the output shows these aliases, instead of http(s)://hostname:port.
The CSN time lags between suppliers and consumers can be displayed in different colors based on their range. The default color set is green for 0-5 minutes lag, yellow for 5-60 minutes lag, and pink for a lag of 60 minutes or more.
The connection parameters for all the servers in a replication topology must be specified within one configuration file. One configuration file, however, may contain information for multiple replication topologies.
Because of the connection parameters, the replication monitoring tool does not need to perform DES decryption of the credentials stored in the Directory Server. Each line in this file could either be a comment started with the # character or a connection entry of the following format: 
host:port:binddn:bindpwd:bindcert
  • host, port, and binddn can be replaced with relevant values or *, or omitted altogether. If host is null or *, the entry may apply to any host that does not have a dedicated entry in the file. If port is null or *, the port will default to the port stored in the current replication agreement. If binddn is null or *, it defaults to cn=Directory Manager.
  • bindcert can be replaced with the full path to the certificate database, null, or *. If bindcert is omitted or replaced with *, the connection will be a simple bind.
For example, the configuration file may appear as follows: 
#Configuration File for Monitoring Replication Via Admin Express
[connection]
*:*:*:mypassword

[alias]
M1 = host1.example.com:10011
C1 = host4.example.com:10021
C2 = host2.example.com:10022

[color]
0 = #ccffcc
5 = #FFFFCC
60 = #FFCCCC
A shadow port can be set in the replication monitor configuration file. For example: 
host:port=shadowport:binddn:bindpwd:bindcert
When the replication monitor finds a replication agreement that uses the specified port, it will use the shadow port to connect to retrieve statistics.

9.4.20. schema-reload.pl (Reload Schema Files Dynamically)

Manually reloads the schema files used by the Red Hat Directory Server instance either in the default location or in user-specified locations.
To run this script, the server must be running. The script creates an entry in the directory that launches this dynamic task.
Syntax

schema-reload.pl -D rootdn -w password | -w - | -j filename [ -d schema_directory ]

Options

 

Table 9.36. schema-reload.pl Options

Option Description
-d schema_directory Gives the full path to the directory where the schema file is located. If this is not specified, the script uses the default schema directory, /etc/dirsrv/schema.

Important

If schema files are not in the default directory, then Directory Server will not use them the next time it restarts unless schema-reload.pl is run again.
-D rootdn Gives the user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config.
-j filename The name of the file containing the password.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

9.4.21. setup-ds.pl

The setup-ds.pl script is used to create a Directory Server instance. Running this script with the -u option after the instances are configured updates the configuration with the latest installed packages.

Note

This script only creates a Directory Server instance, not an Admin Server. For the new instance to work, there has to be an Admin Server and Configuration Directory Server installed on another machine.
Information can be passed with the script or in an .inf file. If no options are used, the setup-ds.pl launches an interactive configuration program.
Both the .inf parameters and command-line arguments are described in the silent configuration section of the Installation Guide.
Syntax

setup-ds.pl [ --debug ] [ --silent ] [ --file=name ] [ --keepcache ] [ --log=name ] [ --update ]

Options

 

Option Alternate Options Description
--silent -s This runs the register script in silent mode, drawing the configuration information from a file (set with the --file parameter) or from arguments passed in the command line rather than interactively.
--file=name -f name
This sets the path and name of the file which contains the configuration settings for the new Directory Server instance. This can be used with the --silent parameter; if used alone, it sets the default values for the setup prompts.
--debug -d[dddd] This parameter turns on debugging information. For the -d flag, increasing the number of d's increases the debug level.
--keepcache -k This saves the temporary installation file (.inf) that is created when the register script is run. This file can then be reused for a silent setup. This file is always generated, but is usually deleted once the install is complete. The file is created as a log file named /tmp/setuprandom.inf, like /tmp/setuplGCZ8H.inf.

Warning

The cache file contains the cleartext passwords supplied during setup. Use appropriate caution and protection with this file.
--logfile name -l This parameter specifies a log file to which to write the output. If this is not set, then the setup information is written to a temporary file. To not use a log file, set the file name to /dev/null.
--update -u This parameter updates existing Directory Server instances. If an installation is broken in some way, this option can be used to update or replace missing packages and then re-register all of the local instances with the Configuration Directory.

9.4.22. setup-ds-admin.pl

The setup-ds-admin.pl script is used to create a Directory Server instance and a new Admin Server instance. Running this script with the -u option after the instances are configured updates the configuration with the latest installed packages.
Information can be passed with the script or in an .inf file. If no options are used, the setup-ds-admin.pl launches an interactive configuration program.
Both the .inf parameters and command-line arguments are described in the silent configuration section of the Installation Guide.
Syntax

setup-ds-admin.pl [ --debug ] [ --silent ] [ --file=name ] [ --keepcache ] [ --log=name ] [ --update ]

Options

 

Option Alternate Options Description
--silent -s This runs the register script in silent mode, drawing the configuration information from a file (set with the --file parameter) or from arguments passed in the command line rather than interactively.
--file=name -f name
This sets the path and name of the file which contains the configuration settings for the new Directory Server instance. This can be used with the --silent parameter; if used alone, it sets the default values for the setup prompts.
--debug -d[dddd] This parameter turns on debugging information. For the -d flag, increasing the number of d's increases the debug level.
--keepcache -k This saves the temporary installation file (.inf) that is created when the register script is run. This file can then be reused for a silent setup. This file is always generated, but is usually deleted once the install is complete. The file is created as a log file named /tmp/setuprandom.inf, like /tmp/setuplGCZ8H.inf.

Warning

The cache file contains the cleartext passwords supplied during setup. Use appropriate caution and protection with this file.
--logfile name -l This parameter specifies a log file to which to write the output. If this is not set, then the setup information is written to a temporary file. To not use a log file, set the file name to /dev/null.
--update -u This parameter updates existing Directory Server instances. If an installation is broken in some way, this option can be used to update or replace missing packages and then re-register all of the local instances with the Configuration Directory.

9.4.23. syntax-validate.pl (Validate Attribute Values)

Syntax validation checks every modification to attributes to make sure that the new value has the required syntax for that attribute type. All attribute syntaxes are validated against the definitions in RFC 4514.
Syntax validation is enabled by default. However, syntax validation only audits changes to attribute values, such as when an attribute is added or modified. It does not validate the syntax of existing attribute values.
Validation of existing attribute values can be done with the syntax validation script. This script checks entries under a specified subtree (in the -b option) and, optionally, only entries which match a specified filter (in the -f option).
If syntax validation is disabled or if a server is migrated, then there may be data in the server which does not conform to attribute syntax requirements. The syntax validation script can be run to evaluate those existing attribute values before enabling syntax validation.
Syntax

syntax-validate.pl -D rootdn -w password | -w - | -j filename -b baseDN [ -f LDAP_filter ]

Options

 

Table 9.37. syntax-validate.pl Options

Option Description
-b baseDN Gives the base DN for the entries to validate.
-D rootdn Gives the user DN with root permissions, such as Directory Manager or whatever the value of the nsslapd-root attribute is under cn=config.
-f LDAP_filter Contains a search filter to use to select a subset of entries to validate. If this is not given, then all entries under the base DN are checked.
-j filename The name of the file containing the password.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

9.4.24. usn-tombstone-cleanup.pl (Remove Deleted Entries)

If the USN Plug-in is enabled, then update sequence numbers (USNs) are set on every entry whenever a normal directory operation, like add or modify, occurs on that entry. This is reflected in the entryUSN operational attribute. This USN is set even when an entry is deleted, and the tombstone entries are maintained by the Directory Server instance.
The usn-tombstone-cleanup.pl script deletes the tombstone entries maintained by the instance if the USN Plug-in is enabled.
To run this script, the server must be running. The script creates an entry in the directory that launches this dynamic task.

Important

This tool can only be run if replication is not enabled. Replication maintains its own tombstone store, and these tombstone entries cannot be deleted by the USN Plug-in; they must be maintained by the replication processes. Thus, Directory Server prevents users from running this script on replicated databases.
Running usn-tombstone-cleanup.pl on a replicated back end will return this error in the command line: 
ldap_add: DSA is unwilling to perform
In the error log, there is a more explicit message that the suffix cannot have tombstone removed because it is replicated. 
[...] usn-plugin - Suffix dc=example,dc=com is replicated. Unwilling to perform cleaning up tombstones.
Syntax

usn-tombstone-cleanup.pl -D rootdn -w password | -w - | -j filename -n backendInstance | -s suffix [ -m maximum_USN ]

Options

Either the -n or the -s option must be specified.

Table 9.38. usn-tombstone-cleanup.pl Options

Option Description
-D rootdn Gives the user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config.
-j filename The name of the file containing the password.
-m maximum_USN Sets the upper bound for entries to delete. All tombstone entries with an entryUSN value up to the specified maximum (inclusive) are deleted, but not past that USN value. If no maximum USN value is set, then all back end tombstone entries are deleted.
-n backendInstance Gives the name of the database containing the entries to clean (delete).
-s suffix Gives the name of the suffix containing the entries to clean (delete).
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

9.4.25. verify-db.pl (Check for Corrupt Databases)

Verifies the back end database files. If the server crashes because of a corrupted database, this script can be used to verify the integrity of the different database files to help isolate any problems.

Important

Never run verify-db.pl when a modify operation is in progress. This command calls the BerkeleyDB utility db_verify and does not perform any locking. This can lead to data corruption if the script is run at the same time as a modify. If that occurs, an entry will be recorded in the error log: 
DB ERROR: db_verify: Page 3527: out-of-order key at entry 42
DB ERROR: db_verify: DB->verify: db/mstest2/uid.db4: DB_VERIFY_BAD: Database
verification failed
Secondary index file uid.db4 in db/mstest2 is corrupted.
Please run db2index(.pl) for reindexing.
Run db2index -t uid to avoid rebuilding all of the indexes or export and reimport all of the databases using db2ldif and ldif2db.
Syntax

verify-db.pl [ -a /path/to/database_directory ] [ -? ]

Options

 

Table 9.39. verify-db.pl Options

Option Description
-a path Gives the path to the database directory. If this option is not passed with the verify-db.pl command, then it uses the default database directory, /var/lib/dirsrv/slapd-instance_name/db.
-? Opens the help page.