Chapter 9. Command-Line Utilities

This chapter contains reference information on command-line utilities used with Red Hat Directory Server (Directory Server). These command-line utilities make it easy to perform administration tasks on the Directory Server.

9.1. ds-replcheck

The ds-replcheck utility compares two Directory Server instances or LDIF-formatted files to identify if they are synchronized. For further details, see the Comparing Two Directory Server Instances section in the Red Hat Directory Server Administration Guide.

For details about the syntax and command-line options, see the ds-replcheck(1) man page.

9.2. ldif

ldif automatically formats LDIF files and creates base-64 encoded attribute values. Base-64 encoding makes it possible to represent binary data, such as a JPEG image, in LDIF. Base-64 encoded data is represented using a double colon (::) symbol. For example:

jpegPhoto:: encoded data

In addition to binary data, other values that must be base-64 encoded can identified with other symbols, including the following:

  • Any value that begins with a space.
  • Any value that begins with a single colon (:).
  • Any value that contains non-ASCII data, including newlines.

The ldif command-line utility will take any input and format it with the correct line continuation and appropriate attribute information. The ldif utility also senses whether the input requires base-64 encoding.

For details about the syntax and command-line options, see the ldif(5) man page.

9.3. dbscan

The dbscan tool analyzes and extracts information from a Directory Server database file. There are four kinds of database files that can be scanned with dbscan:

  • id2entry.db, the main database file for a user database
  • entryrdn.db for a user database
  • secondary index files for a user database, like cn.db
  • numeric_string.db for the changelog in /var/lib/dirsrv/slapd-instance/changelogdb

See Section 2.2.2, “Database Files” for more information on database files.

Database files use the .db2, .db3, .db4, and .db extensions in their filename, depending on the version of Directory Server.

For details about the syntax and command-line options, see the dbscan(1) man page.

Examples

The following are command-line examples of different situations using dbscan to examine the Directory Server databases.

Example 9.1. Dumping the Entry File

dbscan -f /var/lib/dirsrv/slapd-instance/db/userRoot/id2entry.db

Example 9.2. Displaying the Index Keys in cn.db

dbscan -f /var/lib/dirsrv/slapd-instance/db/userRoot/cn.db

Example 9.3. Displaying the Index Keys and the Count of Entries with the Key in mail.db

# dbscan -r -f /var/lib/dirsrv/slapd-instance/db/userRoot/mail.db

Example 9.4. Displaying the Index Keys and the All IDs with More Than 20 IDs in sn.db

# dbscan -r -G 20 -f /var/lib/dirsrv/slapd-instance/db/userRoot/sn.db

Example 9.5. Displaying the Summary of objectclass.db

# dbscan -s -f /var/lib/dirsrv/slapd-instance/db/userRoot/objectclass.db

Example 9.6. Displaying VLV Index File Contents

# dbscan -r -f /var/lib/dirsrv/slapd-instance/db/userRoot/vlv#bymccoupeopledcpeopledccom.db

Example 9.7. Displaying the Changelog File Contents

# dbscan -f /var/lib/dirsrv/slapd-instance/changelogdb/c1a2fc02-1d11b2-8018afa7-fdce000_424c8a000f00.db

Example 9.8. Dumping the Index File uid.db with Raw Mode

# dbscan -R -f /var/lib/dirsrv/slapd-instance/db/userRoot/uid.db

Example 9.9. Displaying the entryID with the Common Name Key "=hr managers"

In this example, the common name key is =hr managers, and the equals sign (=) means the key is an equality index.

# dbscan -k "=hr managers" -r -f /var/lib/dirsrv/slapd-instance/db/userRoot/cn.db

=hr%20managers 7

Example 9.10. Displaying an Entry with the entry ID of 7

# dbscan -K 7 -f /var/lib/dirsrv/slapd-instance/db/userRoot/id2entry.db

id 7 dn: cn=HR Managers,ou=groups,dc=example,dc=com
objectClass: top
objectClass: groupOfUniqueNames
cn: HR Manager
ou: groups
description: People who can manage HR entries
creatorsName: cn=Directory Manager
modifiersName: cn=Directory Manager
createTimestamp: 20050408230424Z
modifyTimestamp: 20050408230424Z
nsUniqueId: 8b465f73-1dd211b2-807fd340-d7f40000 parentid: 3
entryid: 7
entrydn: cn=hr managers,ou=groups,dc=example,dc=com

Example 9.11. Displaying the Contents of entryrdn Index

# dbscan -f /var/lib/dirsrv/slapd-instance/db/userRoot/entryrdn.db -k "dc=example,dc=com"

dc=example,dc=com
  ID: 1; RDN: "dc=example,dc=com"; NRDN: "dc=example,dc=com"
C1:dc=example,dc=com
    ID: 2; RDN: "cn=Directory Administrators"; NRDN: "cn=directory administrators"
2:cn=directory administrators
    ID: 2; RDN: "cn=Directory Administrators"; NRDN: "cn=directory administrators"
P2:cn=directory administrators
    ID: 1; RDN: "dc=example,dc=com"; NRDN: "dc=example,dc=com"
C1:dc=example,dc=com
    ID: 3; RDN: "ou=Groups"; NRDN: "ou=groups"
3:ou=groups
    ID: 3; RDN: "ou=Groups"; NRDN: "ou=groups"
[...]

9.4. ds-logpipe.py

The named pipe log script can replace any of the Directory Server log files (access, errors, and audit) with a named pipe. That pipe can be attached to another script which can process the log data before sending it to output, such as only writing lines that match a certain pattern or are of a certain event type.

Using a named pipe script provides flexibility:

  • The error log level can be set very high for diagnosing an issue to create a log of only the last few hundred or thousand log messages, without a performance hit.
  • Messages can be filtered to keep only certain events of interest. For example, the named pipe script can record only failed BIND attempts in the access log, and other events are discarded.
  • The script can be used to send notifications when events happen, like adding or deleting a user entry or when a specific error occurs.

For details about the syntax and command-line options, see the ds-logpipe.py(1) man page.

Examples

The procedures for configuring the server for named pipe logging are covered in Section 7.5, “Replacing Log Files with a Named Pipe”.

The most basic usage of the named pipe log script points to only the named pipe.

Example 9.12. Basic Named Pipe Log Script

# ds-logpipe.py /var/log/dirsrc/slapd-example/errors.pipe
Note

When the script exits (either because it completes or because it is terminated through a SIGTERM or Ctrl+C), the script dumps the last 1000 lines of the error log to standard output.

The script can be run in the background, and you can interactively monitor the output. In that case, the command kill -1 %1 can be used to tell the script to dump the last 1000 lines of the buffer to stdout, and continue running in the background.

Example 9.13. Running the Named Pipe Log Script in the Background

# ds-logpipe.py /var/log/dirsrc/slapd-example/errors.pipe &

To simply dump the last 1000 lines when the script exits (or is killed or interrupted) and save the output to a file automatically, redirect the script output to a user-defined file.

Example 9.14. Saving the Output from the Named Pipe Log Script

# ds-logpipe.py /var/log/dirsrc/slapd-example/errors.pipe > /etc/dirsrv/myerrors.log 2>&1

The named pipe script can be configured to start and stop automatically with the Directory Server process. This requires the name of the server’s PID file to which to write the script’s PID when the script is running, with the -s argument. The PID for the server can be reference either by pointing to the server PID file or by giving the actual process ID number (if the server process is already running).

Example 9.15. Specifying the Serve PID

# ds-logpipe.py /var/log/dirsrc/slapd-example/errors.pipe --serverpidfile /var/run/dirsrv/slapd-example.pid

A plug-in can be called to read the log data from the named pipe and perform some operation on it.

Example 9.16. Named Pipe Log Script with a Related Plug-in

# ds-logpipe.py /var/log/dirsrc/slapd-example/errors.pipe --plugin=/usr/share/dirsrv/data/logregex.py logregex.regex="warning"

In Example 9.16, “Named Pipe Log Script with a Related Plug-in”, only log lines containing the string warning are stored in the internal buffer and printed when the script exits.

If no plug-in is passed with the script arguments, the script just buffers 1000 log lines (by default) and prints them upon exit. There are two plug-ins provided with the script:

  • logregex.py keeps only log lines that match the given regular expression. The plug-in argument has the format logregex.regex=pattern to specify the string or regular expression to use. There can be multiple logregex.regex arguments which are all treated as AND statements. The error log line must match all given arguments. To allow any matching log lines to be records (OR), use a single logregex.regex argument with a pipe (|) between the strings or expressions. See the pcre or Python regular expression documentation for more information about regular expressions and their syntax.
  • failedbinds.py logs only failed BIND attempts, so this plug-in is only used for the access log. This takes the option failedbinds.logfile=/path/to/access.log, which is the file that the actual log messages are written to. This plug-in is an example of a complex plug-in that does quite a bit of processing and is a good place to reference to do other types of access log processing.

9.5. dn2rdn

Versions of Directory Server older than 9.0 used the entrydn index to help map the entry IDs in the id2entry.db4 database to the full DNs of the entry. (One side effect of this was that modrdn operations could only be done on leaf entries, because there was no way to identify the children of an entry and update their DNs if the parent DN changed.) When subtree-level renames are allowed, then the ID-to-entry mapping is done using the entryrdn index with the id2entry.db database.

After an upgrade, instances of Directory Server may still be using the entrydn index. The dn2rdn tool has one purpose: to convert the entry index mapping from a DN-based format to an RDN-based format, by converting the entrydn index to entryrdn.

Note

The dn2rdn tool is in the /usr/sbin/ directory, since it is always run on the local Directory Server instance.

9.6. pwdhash

The pwdhash utility encrypts a specified plain text password. If a user or the Directory Manager cannot log in, use pwdhash to compare the encrypted passwords. You can also use the generated hash to manually reset the Directory Manager’s password.

The pwdhash utility uses the following storage scheme to encrypt the password:

  • If you pass the -s storage_scheme parameter to pwdhash, the specified scheme will be used.
  • If you pass the -D config_directory parameter to pwdhash, the scheme set in the nsslapd-rootpwstoragescheme attribute will be used.
  • If you neither specify the path to a valid Directory Server configuration directory nor pass a scheme to pwdhash, the utility uses the Directory Server default storage scheme.

For further details about storage schemes, a list of supported values, and the default settings, see Section 4.1.43, “Password Storage Schemes”.

For details about the syntax and command-line options, see the pwdhash(1) man page.