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.
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.
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.
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.
dbscan tool analyzes and extracts information from a Directory Server database file. There are four kinds of database files that can be scanned with
id2entry.db, the main database file for a user database
entryrdn.dbfor a user database
secondary index files for a user database, like
.dbfor the changelog in
See Section 2.2.2, “Database Files” for more information on database files.
Database files use the
.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.
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" [...]
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.
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
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.pykeeps 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.regexarguments 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.regexargument 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.pylogs only failed BIND attempts, so this plug-in is only used for the access log. This takes the option
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.
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
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
dn2rdn tool is in the
/usr/sbin/ directory, since it is always run on the local Directory Server instance.
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.
pwdhash utility uses the following storage scheme to encrypt the password:
If you pass the
-s storage_schemeparameter to
pwdhash, the specified scheme will be used.
If you pass the
-D config_directoryparameter to
pwdhash, the scheme set in the
nsslapd-rootpwstorageschemeattribute 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.