Available command-line tools

PingDirectory provides the following command-line tools, which you can run in interactive, non-interactive, or script mode.

Tools Help
For	Use this option	Example
Information about arguments and subcommands Usage examples	`--help`	`dsconfig --help`
A list of subcommands	`--help-subcommands`	`dsconfig --help-subcommands`
More information about a subcommand	`--help` with the subcommand	`dsconfig list-log-publishers --help`

audit-data-security

Invoke data security audit processing in order to identify potential risks or other notable security characteristics contained in directory data.

This tool schedules an internal task with the server that examines all or a subset of entries in the server, writing a series of reports on potential risks with the data. Reports are written to the output directory organized by backend name and audit items. The list of available auditors can be obtained using dsconfig list-data-security-auditors --advanced --property name. Either the --includeAuditor or the --excludeAuditor arguments can be used to limit the scope of the audit.

Additionally, the entries scanned can be limited by specifying the backends to scan, or by specifying an LDAP filter that is used to selected entries to be processed.

This tool schedules an operation to run within the PingDirectory server’s process. LDAP connection options must be supplied that allow this tool to communicate with the server through its task interface. Tasks can be scheduled to run immediately or at a later time. Once scheduled, tasks can be managed using the manage-tasks tool.

authrate

Perform repeated authentications against the PingDirectory server, where each authentication consists of a search to find a user followed by a bind to verify the credentials for that user.

backup

Back up one or more directory server backends.

Each backend backup is stored in a separate backend backup directory. A backend backup directory can contain multiple backups of the backend. Each backend backup directory contains a backup.info file providing information about each backup in the directory and an archive file for each backup. The name of the archive file includes both the backend ID and the backup ID. The backup ID can be provided to the backup command, or an ID is generated from a current timestamp.

Each backup can be optionally compressed, encrypted, hashed or signed. A backup taken on one system can be restored on another system.

This tool features both an offline mode of operation as well as the ability to schedule an operation to run within the directory server’s process. To schedule an operation supply LDAP connection options that allow this tool to communicate with the server through its task interface. Tasks can be scheduled to run immediately or at a later time. Once scheduled, tasks can be managed using the manage-tasks tool.

base64

Encode raw data using the base64 algorithm or decode base64-encoded data back to its raw representation.

check-replication-domains

Scan the replicationChanges database for all known replication domains and identify any obsolete replicas still listed as part of a topology. Run this tool before upgrading replicated topologies to help avoid lockdown mode.

Learn more about Discovering obsolete replicas.

collect-support-data

Collect and package system information useful in troubleshooting problems. The information is packaged as a zip archive that can be sent to a technical support representative.

Information collected can include configuration files, server monitor entries, portions of log files, JVM thread stack dumps, system metrics, and other data that might be helpful in diagnosing problems, understanding server performance, or otherwise assisting with support requests. Although the tool will do its best to obscure or omit sensitive data, and the entire archive can be encrypted if you desire, you might want to review the resulting support data archive to ensure verify its contents. Further, the archive will include a summary of any potential problems or concerns that are identified in the course of collecting the support data.

compare-ldap-schemas

Compares the schemas of two LDAP servers to identify schema elements that might be present in one but not the other, or elements that might be present in both servers but have differences between them.

config-diff

Compares directory server configurations and produces a dsconfig batch file needed to bring the source inline with the target.

Its uses include comparing multiple servers for configuration differences, producing a batch file to reconfigure a server from scratch from the out-of-the-box configuration, and comparing a local server against an expected configuration.

Both the source and the target configurations can be retrieved over LDAP, accessed from the local server’s file system, extracted from a specific file, or retrieved from every server in a configuration server group. Also, with the exception of accessing a configuration from a specific file, the source and/or target configurations can be compared as they existed at any point in the past, including the baseline, pre-installation configuration.

Some configuration differences (those that will always differ between instances, like instance-name) are excluded by default to reduce the amount of spurious output, but these can be included by specifying the --includeExpectedDifferences command. Further differences can be excluded with the --exclude option.

This tool attempts to generate a batch file that can be applied to the source server without any errors. However, there are some edge case configurations that the tool is not sophisticated enough to handle. For example, it cannot handle two peer configuration objects that would require swapping values for a property (for example, evaluation-order-index) that must be unique within the server. It will still generate a dsconfig batch file that includes these changes, but they might be rejected by the server. In these rare cases, the batch file can be hand edited so that it can be applied to a running server or it can be applied with the server shut down using dsconfig --offline.

create-rc-script

Create a Run Control (RC) script that you can use to start, stop, and restart the PingDirectory server on UNIX-based systems.

create-systemd-script

Create a systemd script to start and stop the PingDirectory server on Linux-based systems.

dbtest

Inspect the contents of the PingDirectory server local DB backends that store their information in Berkeley DB Java Edition databases. Only backends of type local DB can be inspected by this tool.

Each local DB backend has a root container, identified by the backend ID. Each root container has an entry container for each base distinguished name (DN) in the backend. Each entry container has several database containers that store entries, attribute indexes and system indexes. The dbtest command allows the contents of root containers, entry containers and database containers to be inspected.

deliver-one-time-password

Generate and deliver a one-time password to a user through some out-of-band mechanism. That password can then be used to authenticate using the UNBOUNDID-DELIVERED-OTP SASL mechanism.

deliver-password-reset-token

Generate and deliver a single-use token to a user through some out-of-band mechanism. The user can provide that token to the password modify extended request in lieu of the user’s current password in order to select a new password.

dsconfig

View and edit the PingDirectory server configuration. This utility offers three primary modes of operation, the interactive mode, the non-interactive mode, and the batch mode:

The interactive mode supports viewing and editing the configuration using an intuitive, menu driven environment. Running dsconfig in interactive provides a user-friendly, menu-driven interface for accessing and configuring the server. To start dsconfig in interactive command-line mode, simply invoke the dsconfig shell script or batch file without any arguments.
The non-interactive mode provides a simple way to make arbitrary changes to the PingDirectory server by invoking it on the command-line. If you want to use administrative scripts to automate the configuration process, then run the dsconfig command in non-interactive mode.
The batch mode reads multiple dsconfig invocations from a file and executes them sequentially. The batch file provides advantages over standard scripting in that it minimizes LDAP connections and JVM invocations that normally occur with each dsconfig call. You can view the logs/config-audit.log file to review the configuration changes made to the PingDirectory server and to use them in the batch file.

dsjavaproperties

Configure the JVM options used to run the PingDirectory server and its associated tools.

The options managed by this tool are stored in config/java.properties. Typically, you should not edit that file directly. Instead, run the tool specifying --jvmTuningParameter arguments to customize JVM options appropriate for this system. Note that the changes will only apply to this PingDirectory server installation. No modifications will be made to your environment variables.

Memory and other settings for the JVM tools, including the start-server tool, can be tuned during initialization by specifying one or more instances of the --jvmTuningParameter option when invoking this tool. Supported values are as follows:

NONE: Explicitly specify no parameters.
AGGRESSIVE: This system is dedicated to running only this server. The amount of memory allocated to this server will be computed accordingly.
SEMI_AGGRESSIVE: This system is shared by multiple server processes. The amount of memory allocated to this server will be computed accordingly.

If no parameters are specified, the parameters specified by the previous invocation of this tool or setup will be used. Use the NONE option to explicitly specify no parameters.

dsreplication

Manage data replication between two or more PingDirectory server instances.

For replication to work, you must first to enable replication using the enable subcommand. Then, you initialize the contents of one of the servers with the contents of the other using the initialize subcommand.

dump-dns

Obtain a listing of all of the DNs for all entries below a specified base DN in the PingDirectory server.

encode-password

Encode user passwords with a specified storage scheme or determine whether a given clear-text value matches a provided encoded password.

encrypt-file

Encrypt or decrypt data using a key generated from a user-supplied passphrase, a key generated from an encryption settings definition, or a key shared among servers in the topology. The data to be processed can be read from a file or standard input, and the resulting data can be written to a file or standard output. You can use this command to encrypt and subsequently decrypt arbitrary data, or to decrypt encrypted backups, LDAP Data Interchange Format (LDIF) exports, and log files generated by the server.

encryption-settings

Manage the server encryption settings database.

More information about the cipher algorithms and transformations available for use can be found in the Java Cryptography Architecture Reference Guide, as well as the Standard Algorithm Name Documentation for your chosen JDK implementation used by this server.

enter-lockdown-mode

Request that the PingDirectory server enter lockdown mode, during which it only processes operations requested by users holding the lockdown-mode privilege.

While in lockdown mode, the PingDirectory server rejects all requests from users that do not hold the lockdown-mode privilege.

export-ldif

Export data from the PingDirectory server backend in LDIF form.

To export data from a remote PingDirectory server, the server must be running and connection parameters must be supplied. You can specify options to include or exclude specific attributes and branches of the tree, and to include or exclude entries matching a given filter. The data can be appended to an existing file instead of overwriting it, and the output can be optionally compressed.

This tool features both an offline mode of operation as well as the ability to schedule an operation to run within the PingDirectory server’s process. To schedule an operation supply LDAP connection options that allow this tool to communicate with the server through its task interface. Tasks can be scheduled to run immediately or at a later time. Once scheduled, tasks can be managed using the manage-tasks tool.

export-reversible-passwords

Requests that the server export entries from a specified backend in LDIF form, including clear-text representations of any passwords encoded with a reversible storage scheme.

Include the following arguments to configure the output of the tool:

--filter: The export only includes entries matching the specified filter.
--exportNonReversiblePasswords: The export includes entries with non-reversible passwords.
--exportEntriesWithoutPasswords: The export includes entries that don’t have passwords.
--includeAdditionalAttribute: The exported entries include the specified attribute(s) in addition to the user’s DN and password. You can use "*" to include all user attributes and "+" to include all operational attributes.
--includeVirtualAttributes: The exported entries include the values of virtual attributes in addition to real attributes.

This tool can only be used over a secure connection and when authenticated as a user with the permit-export-reversible-passwords privilege. The server encrypts the output using a key generated from either a user-supplied passphrase or an encryption settings definition.

extract-data-recovery-log-changes

Extracts changes matching a given set of criteria from a PingDirectory server audit log so that they can be replayed (for example, as part of a disaster recovery process) or reverted (for example, to back out changes made in error).

This tool is designed to be used in conjunction with the server’s data recovery log files (in the logs/data-recovery directory). It can be used in conjunction with other audit log files, but for best results, the logger should be configured to operate in reversible form, to include the requester DN and IP address, and to include information about any intermediate client control that might have been provided in the request.

This tool must not be used with a log file that the server can update while the tool is running, or that can have some content stored in an unwritten buffer (which is especially likely if the log is compressed or encrypted). To use this tool with the server online, you should only specify a log file that has already been rotated to ensure that no more writes will be made to that file. If necessary, use the rotate-log tool to force the current active file to be rotated.

To use this tool to revert an inappropriate set of changes, run it with --direction revert and an additional set of arguments that identify which changes should be reverted (for example, based on the address of the client, the authorization DN of the requester, the time frame in which the changes were applied, etc.).

To use this tool to replay changes that were previously applied (for example, after restoring an old backup or importing an old LDIF file), run it with --direction replay and an appropriate set of arguments to select the desired set of changes. Also, make sure to use dsreplication pre-external-initialization before performing the restore or import and applying the changes, and then use dsreplication post-external-initialization after the changes have been applied. See the PingDirectory Server Administration Guide for additional information.

This tool will extract changes from the selected log file (and any previously rotated files, unless the --doNotFollowRotationChain argument is provided) and output them in LDIF change format. If the --outputFile argument is provided, then the changes will be written to that file; otherwise, they will be written to standard output. If changes are to be written to a file, then the output will be compressed if the input files were compressed (unless the --doNotCompressOutput argument was provided), and the output will be encrypted if the input files were encrypted (unless the --doNotEncryptOutput argument was provided). You might want to first run the tool without specifying an output file so that you can verify that the selected changes are correct. Once you are certain that the appropriate changes have been selected, you can use a tool like ldapmodify or parallel-update to apply those changes to the server.

generate-totp-shared-secret

Generate a shared secret that you can use to generate time-based one-time password (TOTP) authentication codes for use in authenticating with the UNBOUNDID-TOTP SASL mechanism or with the validate TOTP password extended operation.

identify-references-to-missing-entries

Identify entries containing one or more attributes which reference entries that do not exist. This might require the ability to perform unindexed searches and/or the ability to use the simple paged results control.

identify-unique-attribute-conflicts

Identify unique attribute conflicts. That is, it can identify values of one or more attributes that are supposed to exist only in a single entry but are found in multiple entries.

import-ldif

Import LDIF data into a PingDirectory server backend.

Connection parameters are not required when importing to a local PingDirectory server that is not running. However, connection parameters are required if the server is remote, or if it is running locally and it is inconvenient to have to stop it for the import. You can use the options to include or exclude specific attributes and branches of the tree, and to include or exclude entries matching a given filter. The input file can be compressed.

indent-ldap-filter

Parse a provided LDAP filter string and display it a multi-line form that makes it easier to understand its hierarchy and embedded components. If possible, the tool might also simplify the provided filter in certain ways (for example, by removing unnecessary levels of hierarchy, like an AND embedded in an AND).

ldap-debugger

Intercept and decode LDAP communication.

ldap-diff

Compare the contents of two LDAP servers.

The ldap-diff tool outputs the difference between data stored in two LDAP servers into an LDIF file. This file could be used with the ldapmodify command to bring the source directory server in sync with the target directory server. The specific entries to compare can be controlled with the --searchFilter option. In addition, only a subset of attributes can be compared by listing those attributes as trailing arguments of the command. Specific attributes can also be excluded by prepending a ^ character to the attribute. On Windows operating systems, excluded attributes must be quoted. For example: "^attrToExclude". When retrieving entries from a PingDirectory server, the @objectClassName notation can be used to compare only attributes that are defined for a given objectClass.

This command can be used on servers actively being modified, without reporting false positives caused by replication delays, by checking differing entries multiple times. By default, it will re-check each differing entry twice, pausing two seconds between checks. These settings can be configured with the --numPasses and --secondsBetweenPass options. The output is formatted so that delete operations come first, modify operations come next, and add operations come last. This gives the best chance that the resulting output file can be used to bring the source server into sync with the target server without causing any conflicts. This takes into account attribute uniqueness constraints as well as the requirement that child entries be deleted before parents and parents be added before children.

The directory user specified for performing the searches must be privileged enough to see all of the entries being compared and to issue a long-running, unindexed search. For the PingDirectory server, the out-of-the-box cn=Directory Manager user has these privileges, but you can assign the necessary privileges by setting the following attributes in the user entry

ds-cfg-default-root-privilege-name: unindexed-search
ds-cfg-default-root-privilege-name: bypass-acl
ds-rlim-size-limit: 0
ds-rlim-time-limit: 0
ds-rlim-idle-time-limit: 0
ds-rlim-lookthrough-limit: 0

For servers from other vendors, consult their documentation for configuring the proper privileges.

The ldap-diff tool tries to make efficient use of memory, but it must store the DNs of all entries in memory. For directories that contain tens of millions of entries, the tool might require a few gigabytes of memory. If the progress of the tool slows dramatically, it might be running low on memory. The memory used by ldap-diff can be customized by editing the ldap-diff.java-args parameter in the config/java.properties file and running the dsjavaproperties command.

ldap-result-code

Display and query LDAP result codes.

This tool can be used to list all known defined LDAP result codes, retrieve the name of the result code with a given integer value, or search for all result codes with names containing a given substring.

At most, one of the --list, --int-value, and --search arguments can be provided. If none of them is provided, then the --list option will be chosen by default.

ldapcompare

Perform compare operations in an LDAP directory server. Compare operations can be used to efficiently determine whether a specified entry has a given value.

The exit code for this tool will indicate whether processing was successful or unsuccessful, and to provide a basic indication of the reason for unsuccessful attempts. By default, it will use an exit code of zero (which corresponds to the LDAP 'success' result) if all compare operations completed with a result code of either 'compare false' or 'compare true' (integer values 5 and 6, respectively), but if the --useCompareResultCodeAsExitCode argument is provided, only one compare assertion is performed, and it yields an exit code of 'compare false' or 'compare true', then the numeric value for that result code will be used as the exit code. If any error occurs during processing, then the exit code will be a nonzero value that reflects the first error result that was encountered.

The attribute type and assertion value to use for the compare operations will typically be provided as the first unnamed trailing argument provided on the command line. It should be formatted with the name or OID of the target attribute type followed by a single colon and the string representation of the assertion value. Alternatively, the attribute name or OID can be followed by two colons and the base64-encoded representation of the assertion value, or it can be followed by a colon and a less-than symbol to indicate that the assertion value should be read from a file (in which case the exact bytes of the file, including line breaks, will be used as the assertion value).

The DNs of the entries to compare can either be provided on the command line as additional unnamed trailing arguments after the provided attribute-value assertion, or they can be read from a file whose path is provided using the --dnFile argument.

If the attribute-value assertion is provided on the command line as an unnamed trailing argument, then the same assertion will be performed for all operations. If multiple types of assertions should be performed, then you can use the --assertionFile argument to specify the path to a file containing both attribute-value assertions and entry DNs.

ldapdelete

Delete one or more entries from an LDAP directory server. You can provide the DNs of the entries to delete using named arguments, trailing arguments, a file, or standard input. Alternatively, you can identify entries to delete using a search base DN and filter.

ldapmodify

Apply a set of add, delete, modify, and/or modify DN operations to a directory server. Supply the changes to apply in LDIF format, either from standard input or from a file specified with the ldifFile argument. Change records must be separated by at least one blank line.

ldappasswordmodify

Update the password for a user in an LDAP directory server using the password modify extended operation (as defined in RFC 3062), a standard LDAP modify operation, or an Active Directory-specific modification.

Unless the password change method is explicitly specified (using the --passwordChangeMethod argument), this tool will attempt to automatically determine which method is the most appropriate for the target server using information provided in the server’s root DSE. If the server advertises support for the password modify extended operation, then that method will be used. If it appears to be an Active Directory server, then an Active Directory-specific password-change method will be selected, using a regular LDAP modify operation to update the unicodePwd attribute with a specially encoded value. Otherwise, a regular LDAP modify operation will be used to update the value of a specified password attribute.

The new password to be set for the user can be specified in one of several ways. It can be directly provided on the command line, read from a specified file, interactively prompted from the user, or automatically generated by this tool. If the new password is not specified using any of those methods, and if the password is to be updated using the password modify extended operation, then the new password field of the request will be left blank so that the server generates a new password for the user and includes it in the response to the client. If no new password is specified and some other password change method is selected, then the tool will exit with an error.

The current password for the user can also be specified. This is optional, although some servers might require a user to provide their current password when setting a new one. If a current password is provided (whether given as a command-line argument, read from a specified file, or interactively requested from the user), and if a regular LDAP modify operation is used to change the password, then the resulting modify request will include a deletion of the current value and an addition of the new value. If no current password is provided, then the modify request will replace any existing password(s) with the new value.

ldapsearch

Process one or more searches in an LDAP directory server.

The criteria for the search request can be specified in several different ways, including providing all of the details directly using command-line arguments, providing all of the arguments except the filter using command-line arguments and specifying a file that holds the filters to use, or specifying a file that includes a set of LDAP URLs with the base DN, scope, filter, and attributes to return.

ldif-diff

Compare the contents of two files containing LDIF entries. The output will be an LDIF file containing the add, delete, and modify change records needed to convert the data in the source LDIF file into the data in the target LDIF file.

This tool works best with small LDIF files because it reads the entire contents of the source and target LDIF files into memory so they can be quickly compared. If you encounter an out-of-memory error while running the tool, you might need to increase the amount of memory available to the JVM used to invoke it.

The amount of memory available to the JVM can be customized by invoking the JVM with the -Xms and -Xmx arguments, which specify the initial and maximum amounts of memory that it can use, respectively. These arguments should be immediately followed, without any intervening space, by an integer and a unit to specify the amount of memory to be used. The unit can be either m to indicate that the size is in megabytes, or g to indicate that it is in gigabytes. For example, -Xms512m indicates that the JVM should be given an initial heap size of 512 megabytes, while -Xmx2g indicates that it should be given a maximum heap size of two gigabytes.

When invoking the ldif-diff tool included in the installation of a Ping Identity server product, you can edit the config/java.properties file to specify the arguments to use when invoking the JVM. After modifying the file, run the dsjavaproperties tool to ensure that those changes will be used for subsequent tool invocations.

ldifmodify

Apply a set of changes (including add, delete, modify, and modify DN operations) to a set of entries contained in an LDIF file. The changes will be read from a second file (containing change records rather than entries), and the updated entries will be written to a third LDIF file. Unlike ldapmodify, the ldifmodify command cannot read the changes to apply from standard input.

All of the change records will be read into memory before processing begins, so it is important to ensure that the tool is given enough memory to hold those change records. However, it will only operate on a single source entry at a time, so the size of the source LDIF file does not significantly impact the amount of memory that the tool requires.

Note that the tool will attempt to correctly handle multiple changes affecting the same entry. However, because it only operates on one entry at a time, it cannot always behave in exactly the same way as if it were applying the changes over LDAP to a server populated with the source LDIF file. For example, it is not possible to reject an attempt to delete an entry that has subordinates, so any delete will be treated as a subtree delete.

Further, not all types of modify DN change records are supported. In particular, modify DN change records are not permitted if they target any entry that has been targeted by a previous change record (for example, renaming an entry that was created by a previous add change record).

Finally, it cannot perform other types of validation, like ensuring that all of the necessary superior entries exist when adding a new entry, or ensuring that a modify DN will not introduce a conflict with an existing entry.

ldifsearch

Search one or more LDIF files to identify entries matching a given set of criteria.

leave-lockdown-mode

Request that the PingDirectory server leave lockdown mode and resume normal operation.

While in lockdown mode, the PingDirectory server rejects all requests from users that do not hold the lockdown-mode privilege.

Note that the PingDirectory server can place itself in lockdown mode under certain conditions (for example, if it detects a security problem like a malformed access control rule that might have otherwise resulted in exposure of sensitive data).

list-backends

List the backends and base DNs configured in the PingDirectory server.

load-ldap-schema-file

Loads the schema definitions contained in a specified LDIF file into the schema for a running server. This tool can only be used in conjunction with a server instance running on the local system.

make-ldif

Generate LDIF data based on a definition in a template file. See the server’s config/MakeLDIF directory for example template files. In particular, the examples-of-all-tags.template file shows how to use all of the tags for generating values.

manage-account

Retrieve or update information about the current state of a user account. Processing will be performed using the password policy state extended operation, and you must have the password-reset privilege to use this extended operation.

manage-certificates

Manage certificates and private keys in a JKS, PKCS #12, PKCS #11, or BCFKS key store.

manage-extension

Install or update PingDirectory server extension bundles.

An extension bundle is a package of extension(s) that utilize the Server SDK to extend the functionality of the PingDirectory server. Extension bundles are installed from a zip archive or file system directory. The server will be restarted if running to activate the extension(s).

manage-profile

Generate, compare, install, and replace server profiles.

Server profiles define a format for the configuration of a server, including dsconfig, initial DIT, setup arguments, server SDK extensions, and other files. These are combined into one concrete structure. This tool provides subcommands that can be used to generate a new profile from an existing server, to set up a new server, and to replace an existing server’s profile with a different profile.

A template server profile file structure can be found in the resource/ directory.

manage-tasks

Access information about pending, running, and completed tasks scheduled in the PingDirectory server.

manage-topology

Manage the topology registry.

The topology registry is a branch of the configuration DIT (cn=Topology,cn=config). It stores all metadata about server instances, including their instance and listener certificates, secret keys, server groups and administrative user accounts. In addition, it also stores information about the replication topology (replication server ID and replication domain ID) when replication is enabled among servers in a Directory topology. Last but not least, it stores the license key required to install the server. Changes to the topology registry on one server are automatically mirrored to other servers in the topology. The dsconfig tool, configuration API, or the management console can be used to make changes to the topology registry. This tool allows some additional capability such as exporting the contents of the registry as a JSON file.

migrate-ldap-schema

Migrate schema information from an existing LDAP server into a PingDirectory server instance.

This tool can be used to migrate schema information from an existing LDAP server into this PingDirectory server instance. The source server can be any standards-compliant LDAPv3 server. All attribute type and object class definitions, which are contained in the source LDAP server but not in the target PingDirectory server instance, will be either added to the target instance or written to a schema file.

migrate-sun-ds-config

Update an instance of the PingDirectory server to match the configuration of an existing Sun Java System Directory Server 5.x, 6.x, or 7.x.

This tool can be used to compare the configuration of Sun Java System Directory Server 5.x, 6.x, or 7.x and PingDirectory server instances in order to identify any differences and update the PingDirectory server configuration to more closely match that of the Sun server instance.

modrate

Perform repeated modifications against an LDAP directory server.

move-subtree

Move all entries in a specified subtree from one server to another.

oid-lookup

Search the OID registry to retrieve information about items that match a given OID or name.

The string to use to search the OID registry should be provided as an unnamed trailing argument. All items in the OID registry will be examined, and any items that contain the provided string in its OID, name, type, origin, or URL will be matched. If no search string is provided, the entire OID registry will be displayed.

parallel-update

Use multiple concurrent threads to apply a set of add, delete, modify, and modify DN operations read from an LDIF file.

As with other tools like ldapmodify, changes in the LDIF file to be processed should be ordered such that if there are any dependencies between changes (for example, if one add change record creates a parent entry and another add change record creates a child of that parent), prerequisite changes come before the changes that depend on them. When this tool is preparing to process a change, it will determine whether the new change depends on any other changes that are currently in progress, and if so, will delay processing that change until its dependencies have been satisfied. If a change does not depend on any other changes that are currently being processed, then it can be processed in parallel with those changes.

This tool will keep track of any changes that fail in a way that indicates they succeed if re-tried later (for example, an attempt to add an entry that fails because its parent does not exist, but its parent can be created later in the set of LDIF changes), and can optionally re-try those changes after processing is complete. Any changes that are not retried, as well as changes that still fail after the retry attempts, will be written to a rejects file with information about the reason for the failure so that an administrator can take any necessary further action upon them.

populate-composed-attribute-values

Populate entries in one or more backends with attribute values generated by one or more composed attribute plugins.

This tool uses the configuration from a specified set of composed attribute plugin instances to identify which entries to update and what changes to apply. It can be used as an alternative to exporting the data to LDIF and re-importing to ensure that existing entries have an appropriate set of composed attribute values.

profile-viewer

View information in data files captured by the PingDirectory server profiler.

Profiler data files are generated by the Profiler plugin. To create these data files, set the profile-action attribute of the Profiler configuration object to 'start' to begin collection. Set the profile-action attribute to stop to end collection and have the plugin write the file to logs/profile.{timestamp}.

re-encode-entries

Re-encode all or a specified portion of the entries in a local DB backend.

This tool can be used to initiate a task that will cause a local DB backend to re-encode all or a specified subset of the entries that it contains. The contents of the entries will not be altered, but this provides a useful mechanism for applying significant changes to the way that entries are actually stored in the backend (for example, to apply encoding changes if a feature like data encryption or uncached attributes or entries is enabled).

rebuild-index

Rebuild index data within a backend based on the Berkeley DB Java Edition. Note that this tool uses different approaches to rebuilding indexes based on whether it is running in online mode (as a task) rather than with the server offline. Running in offline mode will often provide significantly better performance and require significantly less database cleaning, particularly for indexes containing keys that match a large number of entries and have high index entry limit and exploded index entry threshold values. Also note that rebuilding an index with the server online will prevent the server from using that index while the rebuild is in progress, so some searches might behave differently while a rebuild is active than when it is not.

An index must be rebuilt if the database already contains data when the index is configured. The backend containing the provided base DN must be a local DB backend. The types of indexes that can be rebuilt include attribute indexes, VLV indexes, and JSON field indexes.

PingDirectory does not support the rebuilding of system indexes, regardless of whether the rebuild is attempted online or offline. If you need to rebuild a system index, you must export the backend to LDIF and re-import it.

register-yubikey-otp-device

Registers a YubiKey OTP device with the PingDirectory server for a specified user so that the device can be used to authenticate that user in conjunction with the UNBOUNDID-YUBIKEY-OTP SASL mechanism. Alternately, it can be used to deregister one or more YubiKey OTP devices for a user so that they can no longer be used to authenticate that user.

reload-http-connection-handler-certificates

Reload HTTPS Connection Handler certificates.

remove-attribute-type-from-schema

Safely remove an attribute type definition from the server schema.

The tool will perform an appropriate set of validation before actually removing the attribute type from the schema. The below conditions must be satisfied before the attribute type can be removed.

The requester must have the update-schema privilege.
The attribute type must not be referenced by any other schema element.
The attribute type must not be defined in any schema file that is included with the PingDirectory server. Only custom attribute types can be removed from the schema.
The attribute type must not be referenced in the server configuration (for example, it must not be indexed by any backend).
The attribute type must not be present in any entry that exists in any backend.

remove-backup

Safely remove a backup from the specified PingDirectory server backend. This tool deletes the specified backup archive and updates the backup descriptor accordingly.

As an alternative to removing a specific backup, you can automatically remove backups outside of specified count or age criteria. The --retainFullBackupCount argument can be used to indicate that the specified number of full backups should be retained, and any other full backups in the directory are eligible to be removed. The --retainFullBackupAge argument can be used to indicate that any full backups older than the specified age are eligible to be removed.

remove-defunct-server

Remove a server from this server’s topology.

This tool will remove the specified server from the topology. In general, the uninstall tool should be used to remove a server from the topology. The remove-defunct-server tool should only be used if a prior attempt to uninstall a server was unsuccessful or the system where the server was installed is no longer available, leaving the server permanently inaccessible from the topology. If the defunct server is online and is able to reach other servers in the topology, running remove-defunct-server from it will cleanly remove it from the topology. If it cannot reach the other servers, then remove-defunct-server must also be run from one of the online servers.

remove-object-class-from-schema

Safely remove an object class definition from the server schema.

The tool will perform an appropriate set of validation before actually removing the object class from the schema. The below conditions must be satisfied before the object class can be removed.

The requester must have the update-schema privilege.
The object class must not be referenced by any other schema element.
The object class must not be defined in any schema file that is included with the PingDirectory server. Only custom object classes can be removed from the schema.
The object class must not be referenced in the server configuration.
The object class must not be present in any entry that exists in any backend.

replace-certificate

Replace the listener certificate for this PingDirectory server instance.

restore

Restore a backup of a PingDirectory server backend.

Only one backend can be restored at a time by the restore command. The PingDirectory server should be stopped unless task connection options are supplied for a running server. You can list the backups contained in a particular backend backup directory. A backup taken on one system can be restored on another system.

revert-update

Revert this server package’s most recent update.

review-license

Review and/or indicate your acceptance of the license agreement defined in legal/LICENSE.txt.

rotate-log

Trigger the rotation of one or more log files.

If the file argument is provided one or more times to specify the target log file paths, then only those log files will be rotated. If the file argument is not given, then the server will trigger rotation for all supported log files.

You must have the config-read and config-write privileges to run this tool, and you must have the necessary access control rights to create and monitor entries in the task backend.

sanitize-log

Sanitize the contents of a server log file to remove potentially sensitive information while still attempting to retain enough information to make it useful for diagnosing problems or understanding load patterns. The sanitization process operates on fields that consist of name-value pairs. The field name is always preserved, but field values might be tokenized or redacted if they might include sensitive information. Supported log file types include the file-based access, error, sync, and resync logs, as well as the operation timing access log and the detailed HTTP operation log. Sanitize the audit log using the scramble-ldif tool.

schedule-exec-task

Schedule an exec task to run a specified command in the server. To run an exec task, several conditions must be satisfied:

The server’s global configuration must have been updated to include com.unboundid.directory.server.tasks.ExecTask in the set of allowed-task values
The requester must have the exec-task privilege
The command to execute must be listed in the exec-command-whitelist.txt file in the server’s config directory.

The absolute path (on the server system) of the command to execute must be specified as the first unnamed trailing argument to this program, and the arguments to provide to that command (if any) should be specified as the remaining trailing arguments. The server root is used as the command’s working directory, so any arguments that represent relative paths are interpreted as relative to that directory.

search-and-mod-rate

Perform repeated searches against an LDAP directory server and modify each entry returned.

search-logs

Search across log files to extract lines matching the provided patterns, like the grep command-line tool. The benefits of using the search-logs tool over grep are its ability to handle multi-line log messages, extract log messages within a given time range, and the inclusion of rotated log files.

searchrate

Perform repeated searches against an LDAP directory server.

server-state

View information about the current state of the PingDirectory server process.

set-delegated-admin-aci

Request that the PingDirectory server assign appropriate ACI for configured delegated administrators of the Delegated Admin API.

setup

Perform the initial setup for a server instance.

This tool features both interactive and non-interactive modes for accepting the product license terms and initially configuring a server instance.

start-server

Start the PingDirectory server.

status

Display basic server information.

This tool prints information about the server, such as version, connection handlers, and data sources. Some information might not be available if the server is not running, or if authentication credentials are missing or do not have sufficient privileges, or if the invoking user does not have sufficient file system access rights.

stop-server

Stop or restart the server.

This tool is used to stop or restart the local instance of the server (by omitting LDAP connection options), or a remote server (by interacting with it over LDAP). In addition, this tool is used to schedule the server for shutdown at a later time using the server’s task interface.

subtree-accessibility

List or update the set of subtree accessibility restrictions defined in the PingDirectory server.

sum-file-sizes

Calculate the sum of the sizes for a set of files.

This tool is used to find the sum of the sizes of one or more files. If any of the files specified is a directory then it will be recursively processed.

summarize-access-log

Examine one or more access log files to display several metrics about operations processed within the server.

sync-pipe-view

PingDataSync only: Display the detailed configuration of a sync pipe or pipes in PingDataSync and all commands necessary to replicate a specified sync pipe.

You can use the sync-pipe-view tool online with the PingDataSync server connection credentials or you can use the tool offline. The sync pipe information can be output in a text, CSV, JSON, or tab-delimited format and can be output to a file. The sync-pipe-view tool features both an interactive mode and a non-interactive mode.

transform-ldif

Apply one or more changes to entries or change records read from an LDIF file, writing the updating records to a new file. This tool can apply a variety of transformations, including scrambling attribute values, redacting attribute values, excluding attributes or entries, replacing existing attributes, adding new attributes, renaming attributes, and moving entries from one subtree to another.

uninstall

Uninstall the PingDirectory server.

This tool removes the entire server or individual server components from the file system. If this server is a member of a replication topology, you must first remove references to this server in the other servers using the dsreplication disable command.

update

Update a deployed server so its version matches the version of this package.

validate-acis

Validate a set of access control definitions contained in an LDAP server (including Sun/Oracle DSEE instances) or an LDIF file to determine whether they are acceptable for use in the PingDirectory server. Note that output generated by this tool will be LDIF, but each entry in the output will have exactly one ACI, so entries which have more than one ACI will appear multiple times in the output with different ACI values.

validate-file-signature

Validate file signatures. For best results, file signatures should be validated by the same instance used to generate the file. However, it might be possible to validate signatures generated on other instances in a replicated topology.

validate-ldap-schema

Validate an LDAP schema read from one or more LDIF files.

validate-ldif

Validate the contents of an LDIF file against the server schema.

verify-index

Verify that indexes in a backend using the Berkeley DB Java Edition are consistent with the entry data contained in the database.

The backend containing the provided base DN must be a local DB backend. The types of indexes that can be verified include system indexes, attribute indexes and VLV indexes. Any errors found during verification are written to the output. The verification process is exhaustive and can take a long time.

watch-entry

Launch a window to watch an LDAP entry for changes. If the entry changes, the background of modified attributes will temporarily be red. Attributes can be modified as well. This tool is primarily intended to demonstrate replication or synchronization functionality.