7.4. Perl Scripts
This section describes the following Perl scripts:
Section 7.4.1, “bak2db.pl (Restores a Database from Backup)”
Section 7.4.2, “cl-dump.pl (Dumps and Decodes the Changelog)”
Section 7.4.4, “db2index.pl (Creates and Generates Indexes)”
Section 7.4.5, “db2ldif.pl (Exports Database Contents to LDIF)”
Section 7.4.8, “ns-accountstatus.pl (Establishes Account Status)”
Section 7.4.9, “ns-activate.pl (Activates an Entry or Group of Entries)”
Section 7.4.10, “ns-inactivate.pl (Inactivates an Entry or Group of Entries)”
Section 7.4.11, “ns-newpwpolicy.pl (Adds Attributes for Fine-Grained Password Policy)”
Section 7.4.12, “repl-monitor.pl (Monitors Replication Status)”
Section 7.4.13, “verify-db.pl (Check for Corrupt Databases)”
Restores a database from a backup.
bak2db.pl [
-v
]
-D rootdn
-w password
[
-a backupDirectory
] [
-t databaseType
] [
-n backend
]
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.
| 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.
|
| -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. Currently, the only possible database type is ldbm.
|
| -v | Verbose mode. |
| -w password | The password associated with the user DN. |
Troubleshoots replication-related problems.
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
]
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.
| Option | Description |
|---|---|
| -c |
Dumps and interprets 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. |
Creates a backup of the database.
db2bak.pl [
-v
]
-D rootdn
-w password
[
-a dirName
]
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.
| Option | Description |
|---|---|
| -a dirName |
The directory where the backup files will be stored. The /var/lib/dirsrv/slapd- 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.
|
| -t |
The database type. Currently, the only possible database type is ldbm.
|
| -v | Verbose mode. |
| -w password | The password associated with the user DN. |
Creates and generates the new set of indexes to be maintained following the modification of indexing entries in the cn=config configuration file.
db2index.pl [
-v
]
-D rootdn
{
-w password -j filename
} [
-n backendInstance
] [
-t attributeName{:indextypes(:mathingrules)}
] [
-T vlvAttributeName
]
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.
| 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. |
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.
db2ldif.pl [
-v
]
-D rootdn
-w password
[
-n backendInstance
|
-s includeSuffix
]
-x excludeSuffix
[
-a outputFile
] [
-N
] [
-r
] [
-C
] [
-u
] [
-U
] [
-m
] [
-o
] [
-1
] [
M
]
To run this script, the server must be running, and either the -n or -s option is required.
| 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.
|
|
| -m | Sets minimal base-64 encoding. | |
| -M | Sets the output LDIF is stored in multiple files. | |
| -n backendInstance | Gives the instance to be exported. | |
| -N | Suppresses printing sequential numbers. | |
| -o | Sets the output LDIF to be stored in one file by default with each instance stored in instance_filename. | |
| -r | Exports a replica. | |
| -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. | |
| -x excludeSuffix | Gives suffixes to be excluded. |
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.
ldif2db.pl [
-v
]
-D rootdn
-w password
[
-n backendInstance
|
-s includeSuffix
]
-x excludeSuffix
[
-O
] [
-c
] [
-g string
] [
-G namespaceId
]
-i filename
| Option | Description |
|---|---|
| -c | Merges chunk size. |
| -D rootdn |
Specifies the user DN with root permissions, such as Directory Manager.
|
| -g string |
Generates a unique ID. Type
When using the -g deterministic
namespaceId is a string of characters in the format 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. |
| -n backendInstance | Specifies the instance to be imported. |
| -O | Requests that only the core db 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. |
| -x excludeSuffix | Specifies the suffixes to be excluded. |
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 Chapter 5, Access Log and Connection Code Reference.
The tool will extract the following information from access logs:
|
|
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”.
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.
logconv.pl [
-S
] [
-E
] [
-d
] [
-X
] [
-v
] [
-h
] [
-s
] [
-V
] [
-y
] [
-p
] [
-efcibaltnxgjuh
]
accessLog
Table 7.25, “logconv.pl Options” describes the logconv.pl command-line 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. |
| -p | Lists open connection ID statistics, which indicates the FDs that are not yet closed. |
| -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.26, “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.
|
| -y | Lists connection latency details, which indicates the overall connection latency. |
| 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.26, “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.
| 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. |
Provides account status information to establish whether an entry or group of entries is inactivated.
ns-accountstatus.pl [
-D rootdn
]
-w password
[
-p port
] [
-h host
]
-I DN
| 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. |
| -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. |
Activates an entry or group of entries.
ns-activate.pl [
-D rootdn
]
-w password
[
-p port
] [
-h host
]
-I DN
| 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. |
| -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. |
Inactivates, and consequently locks, an entry or group of entries.
ns-inactivate.pl [
-D rootdn
]
-w password
[
-p port
] [
-h host
]
-I DN
| 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. |
| -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. |
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 Administration Guide.
ns-newpwdpolicy.pl [
-D rootdn
] {
-w password
|
-w -
|
-j filename
} [
-p port
] [
-h host
]
-U userDN
-S suffixDN
| 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. |
| -w password | Specifies the password associated with the user DN. |
| -w - | Prompts for the password associated with the user DN. |
Shows in-progress status of replication.
repl-monitor.pl
-h host
-p port
-f configFile
[
-u refreshUrl
] [
-t refreshInterval
] [
-r
] [
-v
]
| Option | Description |
|---|---|
| -h host | Specifies the initial replication supplier's host. The default value is the current hostname. |
| -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. |
| -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 the gateway.
|
| -v | Prints the version of this script. |
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.
Verifies the backend database files.
verify-db.pl [
-a /path/to/database_directory
]
| 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-.
|