Available command-line tools
The PingDirectoryProxy server provides command-line tools you can run directly in interactive, non-interactive, or script mode.
For | Use this option | Example |
---|---|---|
Information about arguments and subcommands Usage examples |
|
|
A list of subcommands |
|
|
More information about a subcommand |
|
|
For more information about command-line tools, see Command-line tools. |
|
Perform repeated authentications against an LDAP directory server where each authentication consists of a search to find a user is followed by a bind to verify the credentials for that user. |
||
|
Back up one or more 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 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 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. |
||
|
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, 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 will do its best to obscure or omit sensitive data, and the entire archive can be encrypted if you prefer, 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. |
||
|
Compares 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. 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 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 |
||
|
Create an initial server configuration. This tool is used to configure a basic PingDirectoryProxy server. The tool will prompt for basic information about your topology including directory server instances, their locations, and the credentials for communicating with them. This tool will record the configuration in a The following assumptions are made about the topology to expedite setup:
If your topology does not meet these assumptions, use this tool to define a basic configuration and then use the |
||
|
Create an RC script to start, stop, and restart the server on UNIX-based systems. |
||
|
Create a |
||
|
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. |
||
|
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 place of the user’s current password to select a new password. |
||
|
View and edit the server configuration. This utility offers three primary modes of operation, the interactive mode, the non-interactive mode and batch mode. The interactive mode supports viewing and editing the configuration via an intuitive, menu driven environment. Running The The |
||
|
Configure the Java virtual machine (JVM) arguments used to run the server and associated tools. The options managed by this tool are stored in config/java.properties. Typically you should not edit that file directly but rather run this tool specifying Memory and other settings for the tool JVMs including the start-server tool can be tuned during initialization by specifying one or more instances of the
If no parameters are specified the parameters specified by the previous invocation of this tool or setup will be used. Use the |
||
|
Obtain a listing of all of the distinguished names (DNs) for all entries below a specified base DN in the server. |
||
|
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, 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, as well as the Standard Algorithm Name Documentation for your chosen JDK implementation used by this server. |
||
|
Request that the server enter lockdown mode, during which it only processes operations requested by users holding the While in lockdown mode, the PingDirectoryProxy server rejects all requests from users that do not hold the |
||
|
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. This tool can only be used over a secure connection and when authenticated as a user with the |
||
|
Generate a shared secret that can be used to generate Time-based One-time Password (TOTP) authentication codes for use in authenticating with the |
||
|
Estimates the size in memory of one or more global indexes from the actual number of keys, the configured number of keys and the average key size. The estimate could be slightly higher or lower than the actual size. An estimate can be provided for more than one index in one invocation by providing multiple sets of options. |
||
|
This tool can be used to identify entries containing one or more attributes that reference entries that do not exist. This can require the ability to perform unindexed searches and/or the ability to use the simple paged results control. |
||
|
This tool can be used to identify unique attribute conflicts. That is, it can identify values of one or more attributes which are supposed to exist only in a single entry but are found in multiple entries. |
||
|
Parse a provided LDAP filter string and displays it as a multi-line form that makes it easier to understand its hierarchy and embedded components. If possible, it also simplifies the provided filter in certain ways, such as removing unnecessary levels of hierarchy like an |
||
|
Intercept and decode LDAP communication. |
||
|
Compare the contents of two LDAP directory servers. The 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 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 |
||
|
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 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 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, as trailing arguments, from a file, or from 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 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 to indicate that the server should generate a new password for the user and include 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 delete of the current value and an add of the new value. If no current password is provided, then the modify request will replace any existing password(s) with the new value. |
||
|
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 using command-line arguments, providing all of the arguments except the filter via 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. See the examples below for a number of sample command lines for this tool. |
||
|
Compare the contents of two files containing LDIF entries. The output is 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 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 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. |
||
|
Search one or more LDIF files to identify entries matching a given set of criteria. |
||
|
Request that the server leave lockdown mode and resume normal operation. While in lockdown mode, the PingDirectoryProxy server rejects all requests from users that do not hold the Note that the PingDirectoryProxy server might 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 the backends and base DNs configured in the 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. See the server’s |
||
|
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 and private keys in a JKS, PKCS #12, PKCS #11, or BCFKS key store. |
||
|
Install or update server extension bundles. An extension bundle is a package of extension(s) that utilize the Server SDK to extend the functionality of the 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). |
||
|
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 resource/ directory. |
||
|
Access information about pending, running, and completed tasks scheduled in the server. |
||
|
Tool to manage the topology registry. The topology registry is a branch of the configuration DIT ( |
||
|
Perform repeated modifications against an LDAP directory server. |
||
|
Move all entries in a specified subtree from one server to another. |
||
|
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. |
||
|
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 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. |
||
|
Prepare a PingDirectoryProxy server and a directory server for communication. This tool performs several functions that update a directory server to be used as an external server by the PingDirectoryProxy server. If you use the Among other functions, this tool creates the proxy user account, sets the correct password, and configures the account with required privileges. If necessary you are prompted for manager credentials in order that the tool can perform any required modifications to the external server. When using this tool, specify the LDAP connection options to establish a connection to the external server. Other options are used to specify information about the PingDirectoryProxy server which this tool uses to configure the external server. If a secure connection will be used by the PingDirectoryProxy server to communicate with the external server you can supply the path and password of the truststore to have this tool populate the PingDirectoryProxy server’s truststore with the server certificate of the external server. |
||
|
View information in data files captured by the 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 |
||
|
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 unregister 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 PingDirectoryProxy 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. |
||
|
Reload the contents of the global index. Reloads the contents of the global index for a given base DN. It is possible to reload all configured indexes in the global index (which includes the rdn index and all attribute indexes), or reload only those indexes specified by name. This tool schedules an operation to run within the PingDirectoryProxy 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 |
||
|
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.
This tool schedules an operation to run within the PingDirectoryProxy 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 |
||
|
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 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 |
||
|
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.
This tool schedules an operation to run within the PingDirectoryProxy 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 |
||
|
Replace the listener certificate for this server instance. Only one backend can be restored at a time by the This tool features both an offline mode of operation as well as the ability to schedule an operation to run within the PingDirectoryProxy 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. |
||
|
Restore a backup of a server backend. Only one backend can be restored at a time by the This tool features both an offline mode of operation as well as the ability to schedule an operation to run within the PingDirectoryProxy 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 |
||
|
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 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 This tool schedules an operation to run within the PingDirectoryProxy 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. |
||
|
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 |
||
|
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 server’s global configuration must have been updated to include |
||
|
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 server process. |
||
|
Request that the server assign appropriate access control instruction (ACI) for configured delegated administrators of the Delegated Admin API. |
||
|
Perform the initial setup for the 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 server. |
||
|
Display basic server information. This tool prints information about the server, such as version, connection handlers, and data sources. Some information canht 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 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 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 it will be recursively processed. |
||
|
Examine one or more access log files to display a number of metrics about operations processed within the server. |
||
|
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 server. This tool removes the entire server or individual server components from the file system. If this server is a member of an existing topology, you must first remove references to this server in the other servers using the remove-defunct-server tool. |
||
|
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 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. |