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
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 formatlogregex.regex=
pattern to specify the string or regular expression to use. There can be multiplelogregex.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 singlelogregex.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 optionfailedbinds.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
.
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 topwdhash
, the specified scheme will be used. -
If you pass the
-D config_directory
parameter topwdhash
, the scheme set in thensslapd-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.