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-1    LDIF Command-Line Utilities 

Command-Line Utility	Description
ldif	Formats input by adding base 64 encoding to make it suitable as an attribute value for inclusion in an LDIF file.
fildif	Enables you to create a filtered version of an LDIF input file.

Table 1-2 describes the command-line utilities that enable you to manage and monitor replication:

Table 1-2    Replication Monitoring Tools 

Command-Line Utility	Description
insync	Indicates the synchronization state between a master replica and one or more consumer replicas.
entrycmp	Compares the attributes and values of the same entry on two different servers.
repldisc	Enables you to "discover" a replication topology, constructing a graph of all known servers and displaying a matrix describing the topology.

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

Option

Meaning

-b

Specifies that the ldif utility should interpret the entire input as a single binary value. If -b is not present, each line is considered to be a separate input value. As an alternative to the -b option, you can you can use the :< URL specifier notation, which is in fact simpler to use. For example: jpegphoto:< file:///tmp/myphoto.jpg Although the official notation requires three ///, the use of one / is tolerated.

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:

1. Filter in a list of attributes that must be included in an entry.
2. 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

Option	Meaning
-i	The input LDIF file whose contents will be filtered. This parameter is mandatory.
-f	Forces fildif to overwrite the contents of the specified output file, if it exists.
-o	The output LDIF file in which the filtered results will be stored. If no output file is specified, the default output file is ./output.ldif.
-c	The configuration file in which the filtering configuration is stored.
-b	The pointer entry. This parameter is mandatory and specifies the DN of the entry that will be used as the filtering service configuration entry point. The entry specified by this DN must exist in the configuration file specified by the -c parameter.
-a	The attribute that will be used inside the pointer entry to point to a particular filtering service configuration definition. If this parameter is not present, the default partialReplConfiguration is used.

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.

Table 1-4    Common Replication Monitoring Tool Options

Option	Meaning
HostSpec	HostSpec is defined as: [bindDN[:[password]]@]host[:port] For example "cn=directory manager":mypword@myServer:5201
ServerSpec	The server specification. This can be: -s/-S HostSpec [-c/-C HostSpec -c/-C HostSpec ...] or -c/-C HostSpec [-s/-S HostSpec -s/-S HostSpec ...] where -s is the supplier replica and -c is the consumer replica. You can specify any number of supplier and consumer replicas in this list. If you are using SSL, use -S and -C in the server specification. In addition, if you are using client authentication, HostSpec specifies the certificate name and key password, rather than the bindDN and password. Note: If no -c option is specified, the -s HostSpec may refer to any server, either a consumer or a supplier.
-D	The distinguished name with which to bind to the server. This parameter is optional if the server is configured to support anonymous access. If a DN is specified in the ServerSpec, this overrides the -D option.
-w	The password associated with the distinguished name specified by the -D option. If a password is specified in the ServerSpec, this overrides the -w option.
-n	Specifies that the tools should not run in interactive mode. Running in interactive mode allows you to re-enter the bindDN, password and host and port, if the tool encounters a bind error.
-p	The TCP port used by the Directory Server. The default port is 389. If a port is specified in the ServerSpec, this overrides the -p option.
-j	If specifying the default password at the command line poses a security risk, the password can be stored in a file. The -j option specifies this file.

---

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:

Table 1-5    Common SSL Options

Option	Meaning
-e	The default SSL port.
-J	This option has the same function as the -j option, for the key password.
-K	Specifies the location of the key database used for certificate-based client authentication.
-N	Specifies the certificate name to use for certificate-based client authentication. For example, -N Server-Cert. If this option is specified, the -W option is required.
-P	Specifies the location of the certificate database.
-W	Specifies the password for the certificate database identified by the -P option. For example, -W serverpassword.

---

Caution

When running the replication monitoring tools over SSL, the directory server on which you are running the tools must have a copy of all the certificates used by the other servers in the topology.

---

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:

Table 1-6    insync Specific Options

Option	Meaning
-d	Prints the date of the last change recorded on the master. Using the -d option twice (-d -d) prints the time difference (in days, minutes, and seconds) between the time of the last change and the current time.
-b	The suffix (replica root) that has been specified for replication. If -b is not specified, the delay for all suffixes is printed.
interval	The amount of time (in seconds) after which the synchronization query will start again (in an infinite loop). If no interval is specified, the synchronization query will run only once.
-t	Prints the mode of transport (SSL or CLEAR).

---

Note	If a delay of -1 is returned, insync was unable to obtain any replication information. This may indicate that a total update has just been run, that no changes have been sent to the supplier, or that the Replication Agreement is disabled. The corresponding warning is output in each of these cases.

---

Examples

1. 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


2. 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


3. 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 DN

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, 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

1. 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


2. 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:

Table 1-8    repldisc Specific Options

Option	Meaning
-a	Specifies that only the arcs between pairs of connected hosts are printed. For more information, see the examples that follow. Note: If the total line length of the output exceeds 80 characters, symbolic host names are used, accompanied by a legend. Otherwise, the full host name is printed. Using the -a option ensures that symbolic host names are not used.
-b	The suffix (replica root) that has been specified for replication. If -b is not specified, the topology for all suffixes is printed.
-t	If used with the -a option, this option prints the mode of transport (SSL or CLEAR).

Examples

1. 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  |    |
---+---------------

2. 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


3. 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:

Table 1-9    pwdhash Options

Option	Meaning
-c	Specifies the encrypted password to be compared with. The result of the comparison is either OK or doesn't match.
-s	Generates the encrypted passwords according to the scheme's algorithm. The available schemes are SSHA, SHA, CRYPT and CLEAR.
-D	The instance directory.
-H	Specifies that the passwords are hex-encoded.
password	The clear password/s from which the encrypted form should be generated (or against which the password in the directory should be compared).

Example

# pwdhash -D serverRoot/slapd-serverID -s SSHA myPassword

# {SSHA}mtHyZSHfhOZ4FHmvQe09FQjvLZpnW1wbmw05cw==