Sun ONE Directory Server 5.2 Reference Manual |
Chapter 1 Command-Line Utilities
This chapter contains reference information on the command-line utilities provided with Sun ONE Directory Server 5.2. Note that the LDAP utilities are provided with the Directory Server Resource Kit (DSRK) and are documented in the Directory Server Resource Kit Tools Reference.
This chapter is divided into the following sections:
- Finding and Executing Command-Line Utilities
- Command-Line Utilities Quick Reference
- LDIF Command-Line Utilities
- Replication Monitoring Tools
- Other Tools
Finding and Executing Command-Line Utilities
All the command-line utilities, apart from ldif and pwdhash, are located in the following directory:
ServerRoot/shared/bin
The ldif and pwdhash command-line utilities are located in the following directory:
ServerRoot/bin/slapd/server
Caution
To execute the command-line utilities, you must change to the directory in which they are stored. Although it is possible to set command-path and library-path variables to execute the utilities, this is not recommended procedure. You run the risk of disrupting the correct execution of other utilities and of compromising the security of the system, particularly when you have more than one server version installed.
The same procedure also applies to the Perl scripts provided with Directory Server. For further information on these and other scripts, see Chapter 2 "Command-Line Scripts."
Command-Line Utilities Quick Reference
Table 1-1 describes the command-line utilities that enable you to format LDIF files. Note that the LDAP utilities (ldapsearch, ldapmodify, ldapdelete and ldapcompare) are provided with the Directory Server Resource Kit (DSRK) and are documented in the Directory Server Resource Kit Tools Reference.
Table 1-2 describes the command-line utilities that enable you to manage and monitor replication:
Table 1-3 describes the other command-line utilities provided with Sun ONE Directory Server:
Table 1-3    Other Command-Line Tools
Command-Line Utility
Description
pwdhash
Prints the encrypted form of a password using one of the server's encryption algorithms.
LDIF Command-Line Utilities
ldif
The ldif command-line utility formats input by adding base 64 encoding to make it suitable for inclusion in an LDIF file. This makes it easy to include binary data, such as JPEG images, along with other textual attribute values. In an LDIF file, base 64 encoded attribute values are indicated by a :: after the attribute name, for example:
jpegPhoto:: encoded data
In addition to binary data, other values that must be base 64 encoded include:
- any value that begins with a semicolon (;) or a space
- any value that contains non-ASCII data, including newlines
The ldif command-line utility takes any input and formats it with the correct line continuation and appropriate attribute information.
To undo base 64 encodings in LDIF files, you can use the ldifxform utility in the Directory Server Resource Kit (DSRK), with the -c nob64 option. Note, however, that the resulting file may not be reparsable as LDIF. For more information on the tools provided with the DSRK, see the Directory Server Resource Kit Tools Reference.
Syntax
The ldif command has the following format:
Solaris packages
/usr/sbin/directoryserver ldif [-b] [attrtypes]
Other platforms
ServerRoot/bin/slapd/server ldif [-b] [attrtypes]
Options
fildif
This utility enables you to create a filtered version of any LDIF input file. fildif does not require the directory server to be running.
fildif takes a configuration file as an input parameter. This configuration file must conform to the configuration rules of the Filtering Service included as part of Sun ONE Directory Server, and must contain the specific set and element entries that define these rules. The configuration rules can be defined using the Sun ONE Server Console or at the command line. For more information on the Filtering Service and how it is configured, see Chapter 8, "Managing Replication" in the Sun ONE Directory Server Administration Guide.
Sun ONE Directory Server allows you to configure the following filtering rules:
- Filter in a list of attributes that must be included in an entry.
- Filter out a list of attributes that must be excluded from an entry.
A filtering service configuration is accessed through a pointer entry. The pointer entry is provided to fildif with the -b parameter. A pointer attribute within this entry (provided by the -a parameter) determines the RDN of the filtering service configuration entry to be used for the filtering.
Syntax
The fildif command has the following format:
fildif -i input_file [-f] [-o output_file] [-c config_file] -b pointer_entry
[-a pointer_attr]Options
Exit Status
The following exit values are returned:
0 Successful completion
1 An error occurred
On error, verbose error messages are output to standard output.
Example
# fildif -i data.ldif -o filt_data.ldif -f -c config_fildif.ldif -b "cn=conf_20,cn=sets,cn=filtering service,cn=features,cn=config" -a ds5PartialReplConfiguration
For more information, see the fildif(1M) manual page.
Replication Monitoring Tools
The replication monitoring tools enable you to monitor replication between servers, and to assist in identifying the cause of replication problems.
The following replication monitoring tools are provided:
- insync
- entrycmp
- repldisc
Before describing how these tools work, it is important that you understand the following general replication information.
A Replication Update Vector (RUV) is maintained on each replica. The RUV identifies each master replica within the topology, its Replica ID, and the latest change on each master, expressed as a Change Sequence Number (CSN). A CSN identifies each change made to a master server. A CSN consists of a timestamp, a sequence number, the master Replica ID, and a subsequence number.
The machine on which you are running the insync and entrycmp tools must be able to reach all the specified hosts. If the hosts are unreachable due to a firewall, VPN, or other network setup reasons, you will encounter difficulties using these tools. For the same reason, you should ensure that all the servers are up and running before attempting to use the replication monitoring tools.
The replication monitoring tools connect to the server(s) via LDAP and rely on access to cn=config to obtain the replication status. The user of these tools must therefore have read access to the data under cn=config. This should be taken into account particularly when replication is configured over SSL.
The following section describes the usage of the replication monitoring tools and provides an explanation for each of the options. Certain options are common to all the tools, and are discussed at the beginning of the section.
Common Replication Monitoring Tool Options
The following table describes the options that are common to all the replication monitoring tools.
Caution
When identifying hosts, you must use either symbolic names or IP addresses for all hosts. Using a combination of the two can cause problems.
SSL Options
You can use the following options to specify that the replication monitoring tools use LDAPS when communicating with the Directory Server. You also use these options if you want to use certificate-based authentication. These options are valid only when LDAPS has been turned on and configured. For more information on certificate-based authentication and how to create a certificate database for use with LDAP clients, see Chapter 11, "Managing SSL" in the Sun ONE Directory Server Administration Guide.
You must specify the Directory Server's encrypted port when you use the SSL options:
insync
The insync tool indicates the synchronization state between a master replica and one or more consumer replicas. insync compares the RUVs of replicas and displays the time difference or delay (in seconds) between the servers.
Syntax
insync [-D binddn] [-w password] [-n] [-d] [-t] [-p port] [-e SSL port]
[-j file] [-J file] [-W keypasswd] [-K keydbpath] [-N certname] [-P certdbpath]
[-b ReplicaRoot] ServerSpec [interval]Note that the ServerSpec option includes the -s and -c options, and is described in Table 1-4.
Options
In addition to the Common Replication Monitoring Tool Options and Common SSL Options described previously, insync takes the following options:
Examples
- Specifying one supplier, one consumer, and a repetition interval of 30 seconds. Note that the delay changes to 2, indicating that the consumer is 2 seconds behind the supplier at this point.
# insync -s "cn=directory manager:password@portugal:1389" -c "cn=directory manager:password@france:2389" 30
ReplicaDn Consumer Supplier Delay
l=Europe,o=example.com france:2389 portugal:1389 0
l=States,o=example.com france:2389 portugal:1389 0
l=Europe,o=example.com france:2389 portugal:1389 2
l=States,o=example.com france:2389 portugal:1389 2
l=Europe,o=example.com france:2389 portugal:1389 0
l=States,o=example.com france:2389 portugal:1389 0
- Requesting the date of the last change and restricting the output data to the DN o=example.com:
# insync -s "cn=directory manager:password@portugal:1389" -b o=example.com -d
ReplicaDn Consumer Supplier Delay Last Update
l=Europe,o=example.com france:2389 portugal:1389 0 05/12/2002 16:05:08
l=States,o=example.com france:2389 portugal:1389 0 05/12/2002 16:05:08
- Using certificate-based authentication
# insync -n -K /ServerRoot/alias/slapd-S1-key3.db
-P /ServerRoot/alias/slapd-S1-cert7.db -W password -N "MyCertificate" -S "portugal:24211" -C "france:24213"For more information, see the insync(1M) manual page.
entrycmp
The entrycmp tool compares the same entry on two or more different servers. An entry is retrieved from the master and the entry's nsuniqueid is used to retrieve the same entry from a specified consumer. All the attributes and values of the two entries are compared. If they are identical, the entries are considered to be the same.
Syntax
entrycmp [-D binddn] [-w password] [-n] [-p port] [-e SSL port] [-j file] [-J file]
[-W keypasswd] [-K keydbpath] [-N certname] [-P certdbpath] ServerSpec entry DNNote that the ServerSpec option includes the -s and -c options, and is described in Table 1-4.
Options
In addition to the Common Replication Monitoring Tool Options and Common SSL Options described previously, entrycmp takes the following option:
Table 1-7    entrycmp Specific Options
Option
Meaning
entry DN
Specifies the DN of the entry that you wish to compare.
Examples
- Basic example
# entrycmp -s "cn=directory manager:password@portugal:1389" -c "cn=directory manager:password@france:2389" "ou=people,dc=example,dc=com"
entrycmp: france:2389 - entries match
- SSL example
# entrycmp -n -K /ServerRoot/alias/slapd-S1-key3.db
-P /ServerRoot/alias/slapd-S1-cert7.db -W password -N "MyCertificate" -S "portugal:24211" -C "france:24213" "ou=people,dc=example,dc=com"For more information, see the entrycmp(1M) manual page.
Note Operational attributes are not taken into account when comparing entries.
repldisc
The repldisc utility enables you to "discover" a replication topology. Topology discovery starts with one server and constructs a graph of all known servers (using the RUVs and Replication Agreements). repldisc then prints an adjacency matrix describing the topology.
Note that the HostSpec option includes the -c option, and is described in Table 1-4.
Syntax
repldisc [-D binddn] [-w password] [-n] [-a] [-t] [-p port] [-e SSL port]
[-j file] [-J file] [-W keypasswd] [-K keydbpath] [-N certname] [-P certdbpath] [-b ReplicaRoot] -s/-S HostSpec
Note repldisc takes the host specification from the replication agreement, unless otherwise specified at the command line.
Options
In addition to the Common Replication Monitoring Tool Options and Common SSL Options described previously, repldisc takes the following options:
Examples
- repldisc output in a single master replication scenario.
# repldisc -D "cn=directory manager" -w mypword -b o=rtest -s myserver:1389
Topology for suffix: o=rtest
Legend:
^ : Host on row sends to host on column.
v : Host on row receives from host on column.
x : Host on row and host on column are in MM mode.
H1 : france.example.com:1389
H2 : spain:1389
H3 : portugal:389| H1 | H2 | H3 |
===+===============
H1 | | ^ | |
---+---------------
H2 | v | | ^ |
---+---------------
H3 | | v | |
---+---------------
- The same example as above, but using the -a and -t options.
# repldisc -D "cn=directory manager" -w mypword -b o=rtest -s myserver:1389 -a -t
Topology for suffix: o=rtest
Legend:
The direction of the replication is indicated with arrows.
Single-master: suppliers appear on left, consumers on right (->).
Multi-master : servers are shown linked by a double arrow (<->).france.example.com:1389 -> spain:1389 CLEAR
spain:1389 -> portugal:389 CLEAR
- SSL example
# repldisc -n -K /ServerRoot/alias/slapd-S1-key3.db
-P /ServerRoot/alias/slapd-S1-cert7.db -W password
-N "MyCertificate" -S "portugal:24211" -a -t
Topology for suffix: o=rtest
Legend:
The direction of the replication is indicated with arrows.
Single-master: suppliers appear on left, consumers on right (->).
Multi-master : servers are shown linked by a double arrow (<->).spain:24210 -> portugal:24211 SSL
For more information, see the repldisc(1M) manual page.
Other Tools
pwdhash
The pwdhash command prints the encrypted form of a password using one of the server's encryption algorithms. If a user cannot log in, you can use this command to compare the user's password to the password stored in the directory.
Syntax
pwdhash -D instance_dir [-H] [-c comparepwd | -s scheme] password...
Options
pwdhash takes the following options:
Example
# pwdhash -D serverRoot/slapd-serverID -s SSHA myPassword
# {SSHA}mtHyZSHfhOZ4FHmvQe09FQjvLZpnW1wbmw05cw==