7.4. Perl Scripts

This section describes the following Perl scripts:

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

Restores a database from a backup.
Syntax

bak2db.pl [ -v ] -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 7.18. 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 backend 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.
-v Verbose mode.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

7.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 ] [ -v ]

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

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 7.19. 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.
-v Prints the version of the script.
-w bindPassword Specifies the password for the bind DN.

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

Creates a backup of the database.
Syntax

db2bak.pl [ -v ] -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 7.20. 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.
-v Verbose mode.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

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

db2index.pl [ -v ] -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 7.21. 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.
-v Verbose mode.
-w password Gives the password associated with the user DN.
-w - Prompts for the password associated with the user DN.

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

db2ldif.pl [ -v ] -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 7.22. 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 7.4.7, “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.
-v Verbose mode.
-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.

7.4.6. 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 ] [ -v ]

Options
 

Table 7.23. 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 memberOf attribute is regenerated for every entry in the subtree.
-j filename The name of the file containing the password.
-v Verbose mode.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

7.4.7. 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 [ -v ] -D rootdn { -w password | -w - | -j filename } { -n backendInstance | -s includeSuffix } [ -x excludeSuffix ] [ -O ] [ -c ] [ -g string ] [ -G namespaceId ] [ -i filename ] [ -E ]

Options
 

Table 7.24. 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.
-v Specifies verbose mode.
-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.

7.4.8. 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 5.1, “Access Log Reference”.

NOTE

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

Table 7.25. 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
  • 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 and the total 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 2.3.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 ] [ -X ipAddress ] [ -v ] [ -h ] [ -s size_limit ] [ -V ] [ -efcibaltnxgjuyp ] [ accessLog ]

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

Table 7.26. 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".
-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.
-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 Displays the version number of the logconv.pl script.
-V Enables verbose output. With this option, logconv.pl will compute and display all of the optional lists described in Table 7.27, “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. Wildcards can be used in the filename. It is also possible to specify multiple filenames. However, 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 7.27, “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 7.27. 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.

7.4.9. migrate-ds.pl

The migrate-ds.pl script is used to migrate a Directory Server 7.1 instance to Directory Server 8.1. Migration can happen between instances on on the same machine, on different machines, or on different platforms.

IMPORTANT

Do not run setup-ds-admin.pl for the new Directory Server 8.1 instance before running the migration script if you are migrating from a 7.1 server.
If you are upgrading from a Directory Server 8.0 server, do not run migrate-ds.pl. Run setup-ds-admin.pl -u instead.

NOTE

This script only migrates a Directory Server instance, not an Administration 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 username 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 new 8.1 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.

7.4.10. migrate-ds-admin.pl

The migrate-ds-admin.pl script is used to migrate a Directory Server 7.1 instance to Directory Server 8.1. 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 Administration Server for the 7.1 deployment.

IMPORTANT

Do not run setup-ds-admin.pl for the new Directory Server 8.1 instance before running the migration script if you are migrating from a 7.1 server.
If you are upgrading from a Directory Server 8.0 server, do not run migrate-ds-admin.pl. Run setup-ds-admin.pl -u instead.
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 username 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 new 8.1 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.

7.4.11. 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 7.28. 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 hostname of the Directory Server. The default value is the full hostname 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.

7.4.12. 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 7.29. 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 hostname of the Directory Server. The default value is the full hostname 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.

7.4.13. 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 7.30. 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 hostname of the Directory Server. The default value is the full hostname 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.

7.4.14. 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 [ -v ] [ -? ]

Options

Table 7.31. ns-newpwpolicy.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 hostname of the Directory Server. The default value is localhost or the full hostname 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.
-v Verbose mode.
-w password Specifies the password associated with the user DN.
-? Opens the help page.

7.4.15. 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 Administration Server or Configuration Directory Server.
  • Creating a new, local Administration 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 Administration 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.

7.4.16. 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 removed.slapd-instance.
Syntax

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

Options
 
Option Parameter Description
-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.

7.4.17. 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 ] [ -v ]

Options

Table 7.32. 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 hostname.
-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.
-v Prints the version of this script.

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.

7.4.18. 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 ] [ -v ]

Options
 

Table 7.33. 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/slapd-instance_name/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.
-v Verbose mode.
-w password The password associated with the user DN.
-w - Prompts for the password associated with the user DN.

7.4.19. 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 Administration Server. For the new instance to work, there has to be an Administration 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.

7.4.20. setup-ds-admin.pl

The setup-ds-admin.pl script is used to create a Directory Server instance and a new Administration 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.

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

Verifies the backend 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 7.34. 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.