Available command-line tools
The PingDataSync server provides a variety of command-line tools, which you can run in interactive, non-interactive, or script mode.
The following tables describe the available command-line tools.
Desired information | Command option | Example |
---|---|---|
Information about arguments and subcommands |
|
|
A list of subcommands |
|
|
More information about a subcommand |
|
|
The following table does not contain an exhaustive list of server command-line tools. For the full command-line tool reference, see your |
Command-Line Tool | Description | ||||
---|---|---|---|---|---|
|
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 server entries, 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. To obtain a list of available auditors, use Additionally, the entries to scan can be limited by specifying the backends to scan, or by specifying an Lightweight Directory Access Protocol (LDAP) filter that is used to select the 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. When scheduled, tasks can be managed using the |
||||
|
Perform repeated authentications against an LDAP directory server, where each authentication consists of a search to find a user followed by a bind verifying the credentials for that user. |
||||
|
Back up one or more PingDirectory server backends. Each 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 Each backup can be optionally compressed, encrypted, hashed or signed. A backup executed on one system can be restored on another system. This tool features both an offline mode of operation and 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. When scheduled, tasks can be managed using the |
||||
|
Encode raw data using the base64 algorithm or decode base64-encoded data back to its raw representation. |
||||
|
Collect and package system information useful in troubleshooting problems. The information is packaged as a Information collected can include configuration files, server monitor entries, portions of log files, Java Virtual Machine (JVM) thread-stack dumps, system metrics, and other data that can be helpful in diagnosing problems, understanding server performance, or otherwise assisting with support requests. Although the tool obscures or omits sensitive data, and the entire archive can be encrypted if you prefer, you might want to review the resulting support data archive to verify its contents. The archive includes a summary of any potential problems or concerns that are identified in the course of collecting the support data. |
||||
|
Compares PingDirectory server configurations and produces a 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. With the exception of accessing a configuration from a specific file, the source and target configurations can be compared as they existed at any point in the past, including the baseline, pre-installation configuration. Some configuration differences, such as those that will always differ between instances, like 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, |
||||
|
Create an RC script to start, stop, and restart the PingDirectory server on UNIX-based systems. |
||||
|
Create a |
||||
|
Inspect the contents of PingDirectory server local backends that store their information in Berkeley DB Java Edition databases. Only backends of type local database 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 a number of database containers that store entries, attribute indexes and system indexes. The |
||||
|
Generate and deliver a one-time password to a user through some out-of-band mechanism. That password can then be used to authenticate through the UNBOUNDID-DELIVERED-OTP SASL mechanism. |
||||
|
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 instead of the user’s current password in order to select a new password. |
||||
|
View and edit the PingDirectory server configuration. This utility offers three primary modes of operation:
|
||||
|
Configure the JVM options used to run PingDirectory server and its associated tools. The options managed by this tool are stored in Memory and other settings for the JVM tools, including the
If no parameters are specified, the parameters specified by the previous invocation of this tool or setup will be used. Use the |
||||
|
Manage data replication between two or more PingDirectory server instances. For replication to work, you must first to enable replication using the |
||||
|
Obtain a listing of all of the DNs for all entries below a specified base DN in the PingDirectory server. |
||||
|
Encode user passwords with a specified storage scheme or determine whether a given clear-text value matches a provided encoded password. |
||||
|
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. |
||||
|
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, and the Standard Algorithm Name Documentation for your chosen Java Development Kit (JDK) implementation used by this server. |
||||
|
Request that the PingDirectory server enter lockdown mode, during which it only processes operations requested by users holding the While in lockdown mode, the PingDirectory server rejects all requests from users that do not hold the |
||||
|
Export data from a PingDirectory server backend in LDIF format. To export data from a remote PingDirectory server, the server must be running and the connection parameters must be specified. 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 and 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. When scheduled, tasks can be managed using the manage-tasks tool. |
||||
|
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 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. This 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 To use this tool to revert an inappropriate set of changes, run it with 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 This tool extracts changes from the selected log file (and any previously rotated files, unless the After you’re certain that the appropriate changes have been selected, you can use a tool like |
||||
|
Generate a shared secret that can be used to generate time-based one-time password (TOTP) authentication codes for use in authenticating with the UNBOUNDID-TOTP SASL mechanism, or in conjunction with the validate TOTP password extended operation. |
||||
|
Identify entries containing one or more attributes that reference entries that do not exist. This might require the ability to perform unindexed searches or the ability to use the simple paged results control. |
||||
|
Identify unique attribute conflicts. 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 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 PingDirectory server is remote, or if the PingDirectory server 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. This tool features both an offline mode of operation and 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. When scheduled, tasks can be managed using the |
||||
|
Parse a provided LDAP filter string and displays it in a multi-line form that makes it easier to understand the hierarchy and embedded components. If possible, the tools simplifies the provided filter in certain ways, such as by removing unnecessary levels of hierarchy, like an |
||||
|
Intercept and decode LDAP communication. |
||||
|
Compare the contents of two LDAP servers. The You can exclude specific attributes by prepending a This command can be used on servers actively being modified, without reporting false positives due to 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 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
For servers from other vendors, consult their documentation for configuring the proper privileges. The |
||||
|
Display and query LDAP result codes. This tool can be used to list all result codes defined in the PingDirectory server, retrieve the name of the result code with a specified integer value, or list all result codes whose names contain a specified substring. |
||||
|
Perform The exit code for this tool indicates whether processing was successful or unsuccessful and provide a basic indication of the reason for unsuccessful attempts. By default, it uses 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). However, if the 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 character 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 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 |
||||
|
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. |
||||
|
Apply a set of |
||||
|
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 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 exits 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 |
||||
|
Process one or more searches in an LDAP directory server. The criteria for the search request can be specified in a number of different ways, including providing all of the details directly through command-line arguments, providing all of the arguments except the filter through 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. |
||||
|
Compare the contents of two files containing LDIF entries. The output will be an LDIF file containing the 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 When invoking the |
||||
|
Apply a set of changes (including All of the change records are 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 only operates on a single source entry at a time, so that the size of the source LDIF file does not significantly impact the amount of memory that the tool requires.
Not all types of 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 |
||||
|
Search one or more LDIF files to identify entries matching a given set of criteria. |
||||
|
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.
|
||||
|
List the backends and base DNs configured in the PingDirectory server. |
||||
|
Load 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. |
||||
|
Generate LDIF data based on a definition in a template file. For example template files, see the server’s |
||||
|
Retrieve or update information about the current state of a user account. Processing is performed using the password policy state extended operation, and you must have the |
||||
|
Manage certificates and private keys in a JKS or PKCS #12 key store. |
||||
|
Install or update PingDirectory server extension bundles. An extension bundle is a package of extensions that use the Server SDK to extend the functionality of the PingDirectory server. Extension bundles are installed from a |
||||
|
Generate, compare, install, and replace server profiles. Server profiles define a format for the configuration of a server, including A template server profile file structure can be found in the |
||||
|
Access information about pending, running, and completed tasks scheduled in the PingDirectory server. |
||||
|
Manage the topology registry. The topology registry is a branch of the configuration DIT ( |
||||
|
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 objectclass definitions that 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. |
||||
|
Update an instance of the PingDirectory server to match the configuration of an existing Oracle Java System Directory Server 5.x, 6.x, or 7.x. This tool can be used to compare the configuration of Oracle 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 Oracle server instance. |
||||
|
Perform repeated modifications against an LDAP directory server. |
||||
|
Move all entries in a specified subtree from one server to another. |
||||
|
Perform |
||||
|
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. 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. When scheduled, tasks can be managed using the manage-tasks tool. |
||||
|
View information in data files captured by the PingDataSync 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 |
||||
|
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). 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. When scheduled, tasks can be managed using the manage-tasks tool. |
||||
|
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.
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.
This tool features both an offline mode of operation and 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. When scheduled, tasks can be managed using the manage-tasks tool. |
||||
|
Register 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 HTTPS Connection Handler certificates. 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. When scheduled, tasks can be managed using the |
||||
|
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 |
||||
|
Remove a server from this server’s topology. This tool will remove the specified server from the topology. In general, the |
||||
|
Replace the listener certificate for this PingDirectory server instance. |
||||
|
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. This tool features both an offline mode of operation and 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. When scheduled, tasks can be managed using the manage-tasks tool. |
||||
|
Revert this server package’s most recent update. |
||||
|
Review and indicate your acceptance of the license agreement defined in |
||||
|
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 are rotated. If the file argument is not given, then the server triggers rotation for all supported log files. You must have the 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. When scheduled, tasks can be managed using the manage-tasks tool. |
||||
|
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, the operation timing access log, and the detailed HTTP operation log. Sanitize the audit log using the |
||||
|
Schedule an exec task to run a specified command in the server. To run an exec task, a number of conditions must be satisfied:
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. |
||||
|
Perform repeated searches against an LDAP directory server and modify each entry returned. |
||||
|
Search across log files to extract lines matching the provided patterns, like the |
||||
|
Perform repeated searches against an LDAP directory server. |
||||
|
View information about the current state of the PingDataSync server process. |
||||
|
Request that the PingDirectory server assign the appropriate access control instruction (ACI) for configured delegated administrators of the Delegated Admin API. |
||||
|
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 the PingDirectory server. |
||||
|
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, 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 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. |
||||
|
List or update the set of subtree accessibility restrictions defined in the PingDirectory server. |
||||
|
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 the file is recursively processed. |
||||
|
Examine one or more access log files to display a number of metrics about operations processed within the server. |
||||
|
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 |
||||
|
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 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 |
||||
|
Update a deployed server so its version matches the version of this package. |
||||
|
Validate a set of access control definitions contained in an LDAP server, including Oracle DSEE instances, or an LDIF file to determine whether they are acceptable for use in the PingDirectory server.
|
||||
|
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 an LDAP schema read from one or more LDIF files. |
||||
|
Validate the contents of an LDIF file against the server schema. |
||||
|
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. |
||||
|
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. |