Command-line tools

PingAuthorize Server provides a full suite of command-line tools to administer the server. You can run these tools in interactive, noninteractive, or script mode.

Most of these tools are in the bin directory for Linux systems and the bat directory for Microsoft Windows systems; however, some of the tools are in the root directory of the distribution.

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`

For more information and examples, see the PingAuthorize Command-Line Tool Reference at docs/cli/index.html.

Tool Description

backup

Run full or incremental backups on one or more PingAuthorize Server backends.

This tools supports the use of a properties file to pass command-line arguments. See Saving command options in a file.

base64

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

collect-support-data

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

config-diff

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

create-initial-config

Create an initial PingAuthorize Server configuration.

create-rc-script

Create a Run Control (RC) script to start, stop, and restart the PingAuthorize Server on UNIX-based systems.

create-systemd-script

Create a systemd script to start and stop the PingAuthorize Server on Linux-based systems.

docker-pre-start-config

Run this tool before starting PingAuthorize Server to make configuration changes to the server that depend on the running container’s environment.

dsconfig

View and edit the PingAuthorize Server configuration.

dsjavaproperties

Configure the JVM options used to run PingAuthorize Server and its associated tools.

Before launching the command, edit the properties file located in config/java.properties to specify the desired JVM options and JAVA_HOME environment variable.

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, LDIF exports, and log files generated by the server.

encryption-settings

Manage the server encryption settings database.

ldap-diff

Compare the contents of two LDAP servers.

ldap-result-code

Display and query LDAP result codes.

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.

ldapdelete

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.

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.

ldapsearch

Process one or more searches in an LDAP directory server.

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.

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, ldifmodify cannot read the changes to apply from standard input.

ldifsearch

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

list-backends

List the backends and base DNs configured in PingAuthorize Server.

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

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

manage-extension

Install or update PingAuthorize Server extension bundles.

manage-profile

Generate, compare, install, and replace server profiles.

manage-tasks

Access information about pending, running, and completed tasks scheduled in the PingAuthorize Server.

manage-topology

Tool to manage the topology registry.

prepare-external-store

Prepare a PingAuthorize Server and an external server for communication.

reload-http-connection-handler-certificates

Reload HTTPS Connection Handler certificates.

remove-backup

Safely remove a backup and optionally all of its dependent backups from the specified PingAuthorize Server backend.

remove-defunct-server

Remove a server from this server’s topology.

replace-certificate

Replace the listener certificate for this PingAuthorize Server server instance.

restore

Restore a backup of a PingAuthorize Server backend.

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.

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.

To sanitize error log content as it’s being written, see Log Sanitization.

schedule-exec-task

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 com.unboundid.directory.server.tasks.ExecTask in the set of allowed-task values, the requester must have the exec-task privilege, and 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-logs

Search across log files to extract lines matching the provided patterns, like the grep command-line tool. The benefits of using this 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.

server-state

View information about the current state of the PingAuthorize Server process.

setup

Perform the initial setup for a server instance.

start-server

Start the PingAuthorize Server.

status

Display basic server information.

stop-server

Stop or restart the server.

sum-file-sizes

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

uninstall

Uninstall PingAuthorize Server.

update

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

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.