--- title: Command-line interface description: This topic describes the basic command-line interface (CLI). The CLI includes a number of utilities for managing an IDM instance. Each utility is subcommand of the cli.sh (UNIX) or cli.bat (Windows) scripts. To use the utilities, you can run the applicable subcommand or launch the cli script and then run the utility. For example, to run the encrypt utility on a UNIX system: component: pingidm version: 8.1 page_id: pingidm:setup-guide:chap-cli canonical_url: https://docs.pingidentity.com/pingidm/8.1/setup-guide/chap-cli.html keywords: ["Setup & Configuration", "CLI"] section_ids: cli-configexport: configexport cli-configimport: configimport cli-configureconnector: configureconnector cli-encrypt: encrypt` cli-secure-hash: secureHash cli-keytool: keytool cli-validate: validate --- # Command-line interface This topic describes the basic command-line interface (CLI). The CLI includes a number of utilities for managing an IDM instance. Each utility is subcommand of the `cli.sh` (UNIX) or `cli.bat` (Windows) scripts. To use the utilities, you can run the applicable subcommand or launch the `cli` script and then run the utility. For example, to run the `encrypt` utility on a UNIX system: ```console /path/to/openidm/cli.sh Using boot properties at /path/to/openidm/resolver/boot.properties openidm# encrypt ... ``` The command-line utilities run with the security properties defined in your project's `conf/secrets.json` file. If you run the `cli.sh` command by itself, it opens an IDM-specific shell prompt: ```console openidm# ``` | | | | - | --------------------------------------------------------------------------------------------------------------------------------------- | | | For more information about startup and shutdown scripts, refer to [Startup configuration](../install-guide/startup-configuration.html). | The following topics describe the subcommands and their use. Examples assume you are running the commands on a UNIX system. For Windows systems, use `cli.bat` instead of `cli.sh`. For a list of subcommands available from the `openidm#` prompt, run the `cli.sh help` command. The following `help` and `exit` options are self-explanatory. The other subcommands are explained in the subsections that follow. ``` local:secureHash Hash the input string. local:keytool Export or import a SecretKeyEntry. The Java Keytool does not allow for exporting or importing SecretKeyEntries. local:encrypt Encrypt the input string. local:validate Validates all json configuration files in the configuration (default: /conf) folder. basic:help Displays available commands. basic:exit Exit from the console. remote:configureconnector Generate connector configuration. remote:configexport Exports all configurations. remote:configimport Imports the configuration set from local file/directory. ``` The following options are common to the `configexport`, `` configimport` ``, and `configureconnector` subcommands: * -u or --user USER\[:PASSWORD] Allows you to specify the server user and password. Specifying a username is mandatory. If you do not specify a username, the following error is output to the OSGi console: `Remote operation failed: Unauthorized`. If you do not specify a password, you are prompted for one. This option is used by all three subcommands. * \--url URL The URL of the REST service. The default URL is `http://localhost:8080/openidm/`. This can be used to import configuration files from a remote running IDM instance. This option is used by all three subcommands. * -P or --port PORT The port number associated with the REST service. If specified, this option overrides any port number specified with the `--url` option. The default port is `8080`. This option is used by all three subcommands. ## `configexport` The `configexport` subcommand exports all configuration objects to a specified location, enabling you to reuse a system configuration in another environment. For example, you can test a configuration in a development environment, then export it and import it into a production environment. This subcommand also enables you to inspect the active configuration of an IDM instance. OpenIDM must be running when you execute this command. Usage is as follows: ```bash ./cli.sh configexport --user username:password export-location ``` For example: ```bash ./cli.sh configexport --user openidm-admin:openidm-admin /tmp/conf ``` On Windows systems, the export-location must be provided in quotation marks, for example: ```dos C:\openidm\cli.bat configexport --user openidm-admin:openidm-admin "C:\temp\openidm" ``` Configuration objects are exported as `.json` files to the specified directory. The command creates the directory if needed. Configuration files that are present in this directory are renamed as backup files, with a timestamp; for example, `audit.json.2014-02-19T12-00-28.bkp`, and are not overwritten. The following configuration objects are exported: * The internal repository table configuration (`repo.ds.json` or `repo.jdbc.json` ) and the datasource connection configuration, for JDBC repositories (`datasource.jdbc-default.json` ) * The script configuration (`script.json` ) * The log configuration (`audit.json` ) * The authentication configuration (`authentication.json` ) * The cluster configuration (`cluster.json` ) * The configuration of the outbound email service (`external.email.json)` * Custom configuration information (`info-name.json` ) * The managed object configuration (`managed.json` ) * The connector configuration (`provisioner.openicf-*.json` ) * The router service configuration (`router.json` ) * The scheduler service configuration (`scheduler.json` ) * Any configured schedules (`schedule-*.json` ) * Standard security questions (`selfservice.kba.json)` * The [mapping](../synchronization-guide/mappings.html) configuration * If workflows are defined, the configuration of the workflow engine (`workflow.json` ) and the workflow access configuration (`process-access.json` ) * Any configuration files related to the user interface (`ui-*.json` ) * The configuration of any custom endpoints (`endpoint-*.json` ) * The configuration of servlet filters (`servletfilter-*.json` ) * The policy configuration (`policy.json` ) ## `configimport` The `configimport` subcommand imports configuration objects from the specified directory, enabling you to reuse a system configuration from another environment. For example, you can test a configuration in a development environment, then export it and import it into a production environment. The command updates the existing configuration from the import-location over the REST interface. By default, if configuration objects are present in the import-location and not in the existing configuration, these objects are added. If configuration objects are present in the existing location but not in the import-location, these objects are left untouched in the existing configuration. The subcommand takes the following options: * `-r`, `--replaceall`, `--replaceAll` Replaces the entire list of configuration files with the files in the specified import location. | | | | - | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | This option wipes out the existing configuration and replaces it with the configuration in the import-location. Objects in the existing configuration that are not present in the import-location are deleted. | * `--retries` (integer) This option specifies the number of times the command should attempt to update the configuration if the server is not ready. Default value : 10 * `--retryDelay` (integer) This option specifies the delay (in milliseconds) between configuration update retries if the server is not ready. Default value : 500 Usage is as follows: ```bash ./cli.sh configimport --user username:password [--replaceAll] [--retries integer] [--retryDelay integer] import-location ``` For example: ```bash ./cli.sh configimport --user openidm-admin:openidm-admin --retries 5 --retryDelay 250 --replaceAll /tmp/conf ``` On Windows systems, the import-location must be provided in quotation marks, for example: ```dos C:\openidm\cli.bat configimport --user openidm-admin:openidm-admin --replaceAll "C:\temp\openidm" ``` Configuration objects are imported as `.json` files from the specified directory to the `conf` directory. The configuration objects that are imported are the same as those for the `export` command described in the previous section. ## `configureconnector` The `configureconnector` subcommand generates a configuration for an ICF connector. Usage is as follows: ```bash ./cli.sh configureconnector --user username:password --name connector-name ``` Select the type of connector that you want to configure. The following example configures a new CSV connector: ```none ./cli.sh configureconnector --user openidm-admin:openidm-admin --name myCsvConnector Executing ./cli.sh... Starting shell in /path/to/openidm Mar 26, 2020 06:08:52 PM org.forgerock.openidm.core.FilePropertyAccessor loadProps 0. SSH Connector version 1.5.20.31 1. ServiceNow Connector version 1.5.20.31 2. Scripted SQL Connector version 1.5.20.31 3. Scripted REST Connector version 1.5.20.31 4. Scim Connector version 1.5.20.31 5. Salesforce Connector version 1.5.20.31 6. MSGraphAPI Connector version 1.5.20.31 7. MongoDB Connector version 1.5.20.31 8. Marketo Connector version 1.5.20.31 9. LDAP Connector version 1.5.20.31 10. Kerberos Connector version 1.5.20.31 11. Scripted Poolable Groovy Connector version 1.5.20.31 12. Scripted Groovy Connector version 1.5.20.31 13. GoogleApps Connector version 1.5.20.31 14. Database Table Connector version 1.5.20.31 15. CSV File Connector version 1.5.20.31 16. Adobe Marketing Cloud Connector version 1.5.20.31 17. Exit Select [0..17]: 15 Edit the configuration file and run the command again. The configuration was saved to /path/to/openidm/temp/provisioner.openicf-myCsvConnector.json ``` The basic configuration is saved in a file named `/openidm/temp/provisioner.openicf-connector-name.json`. Edit at least the `configurationProperties` parameter in this file to complete the connector configuration. For example, for a CSV connector: ```json "configurationProperties" : { "headerPassword" : "password", "csvFile" : "&{idm.instance.dir}/data/csvConnectorData.csv", "newlineString" : "\n", "headerUid" : "uid", "quoteCharacter" : "\"", "fieldDelimiter" : ",", "syncFileRetentionCount" : 3 } ``` For more information about the connector configuration properties, refer to [Configure connectors](https://docs.pingidentity.com/openicf/connector-reference/configure-connector.html). When you have modified the file, rerun the `configureconnector` command so that IDM can pick up the new connector configuration: ``` ./cli.sh configureconnector --user openidm-admin:openidm-admin --name myCsvConnector Executing ./cli.sh... Starting shell in /path/to/openidm Using boot properties at /path/to/openidm/resolver/boot.properties Configuration was found and read from: /path/to/openidm/temp/provisioner.openicf-myCsvConnector.json ``` Copy the new `provisioner.openicf-myCsvConnector.json` file to your project's `conf/` subdirectory. You can also configure connectors over the REST interface or through the admin UI. For more information, refer to [Configure connectors](https://docs.pingidentity.com/openicf/connector-reference/configure-connector.html). ## `` encrypt` `` The `encrypt` subcommand encrypts an input string, or JSON object, provided at the command line. This subcommand can be used to encrypt passwords or other sensitive data to be stored in the repository. The encrypted value is output to standard output and provides details of the cryptography key used to encrypt the data. Usage is as follows: ```bash ./cli.sh encrypt [-j] string ``` If you do not enter the string as part of the command, the command prompts for the string to be encrypted. If you enter the string as part of the command, special characters, such as quotation marks, must be escaped. * -j or --json Indicates that the string to be encrypted is a JSON object, and validates the object. If the object is malformed JSON and you use the `-j` option, the command throws an error. It is easier to input JSON objects in interactive mode. If you input the JSON object on the command-line, the object must be surrounded by quotes, and any special characters, including curly braces, must be escaped. The rules for escaping these characters are fairly complex. For more information, refer to the [OSGi specification](https://docs.osgi.org/specification/). For example: ```bash ./cli.sh encrypt \ --json '\{\"password\":\"myPassw0rd\"\}' ``` The following example encrypts a normal string value: ```bash ./cli.sh encrypt \ mypassword Executing ./cli.sh... Starting shell in /path/to/openidm -----BEGIN ENCRYPTED VALUE----- { "$crypto" : { "type" : "x-simple-encryption", "value" : { "cipher" : "AES/CBC/PKCS5Padding", "stableId" : "openidm-sym-default", "salt" : "vdz6bUztiT6QsExNrZQAEA==", "data" : "RgMLRbX0guxF80nwrtaZkkoFFGqSQdNWF7Ve0zS+N1I=", "keySize" : 16, "purpose" : "idm.config.encryption", "iv" : "R9w1TcWfbd9FPmOjfvMhZQ==", "mac" : "9pXtSKAt9+dO3Mu0NlrJsQ==" } } } ------END ENCRYPTED VALUE------ ``` The following example prompts for a JSON object to be encrypted: ``` ./cli.sh encrypt --json Using boot properties at /path/to/openidm/resolver/boot.properties Enter the Json value > Press ctrl-D to finish input Start data input: {"password":"myPassw0rd"} ^D -----BEGIN ENCRYPTED VALUE----- { "$crypto" : { "type" : "x-simple-encryption", "value" : { "cipher" : "AES/CBC/PKCS5Padding", "stableId" : "openidm-sym-default", "salt" : "vdz6bUztiT6QsExNrZQAEA==", "data" : "RgMLRbX0guxF80nwrtaZkkoFFGqSQdNWF7Ve0zS+N1I=", "keySize" : 16, "purpose" : "idm.config.encryption", "iv" : "R9w1TcWfbd9FPmOjfvMhZQ==", "mac" : "9pXtSKAt9+dO3Mu0NlrJsQ==" } } } ------END ENCRYPTED VALUE------ ``` ## `secureHash` The `secureHash` subcommand hashes an input string or JSON object using the specified hash algorithm configuration. Use this subcommand to hash password values or other sensitive data to be stored in the repository. The hashed value is output to standard output and provides details of the algorithm configuration used to hash the data. Usage is as follows: ``` /path/to/openidm/cli.sh secureHash --algorithm --config [--json] string ``` * -a or --algorithm Specifies the hash algorithm to use. * -c or --config Lets you provide additional hashing configuration options, as a JSON object. For a list of supported hash algorithms and their configuration, refer to [Salted Hash Algorithms](../security-guide/encoding-attribute-values.html#encoding-salted-hash). * -j or --json Indicates that the string to be encrypted is a JSON object, and validates the object. If the object is malformed JSON and you use the `-j` option, the command throws an error. It is easier to input JSON objects in interactive mode. If you input the JSON object on the command-line, the object must be surrounded by quotes, and any special characters, including curly braces, must be escaped. The rules for escaping these characters are fairly complex. For more information, refer to the [OSGi specification](https://docs.osgi.org/specification/). For example: ``` /path/to/openidm/cli.sh secureHash \ --algorithm SHA-384 \ --json '\{\"password\":\"myPassw0rd\"\}' ``` If you do not enter the string as part of the command, the command prompts for the string to be hashed. If you enter the string as part of the command, any special characters, for example quotation marks, must be escaped. The following example hashes a password value (`mypassword`) using the `PBKDF2` algorithm: ``` /path/to/openidm/cli.sh secureHash \ --algorithm PBKDF2 \ --config '{\"hashLength\":16\,\"saltLength\":16\,\"iterations\":20000\,\"hmac\":\"SHA3-256\"}' \ "mypassword" Executing ./cli.sh... Starting shell in /path/to/openidm ... -----BEGIN HASHED VALUE----- { "$crypto" : { "value" : { "algorithm" : "PBKDF2", "data" : "9/1IIaAVxAMFdCzlMGtkXMmotKqBafIdx2KFUeKHX0k=", "config" : { "hashLength" : 16, "saltLength" : 16, "iterations" : 20000, "hmac" : "SHA3-256" } }, "type" : "salted-hash" } } ------END HASHED VALUE------ ``` The following example prompts for a JSON object to be hashed: ``` /path/to/openidm/cli.sh secureHash --algorithm SHA-384 --json Executing ./cli.sh... Executing ./cli.sh... Starting shell in /path/to/openidm Nov 14, 2017 1:24:26 PM org.forgerock.openidm.core.FilePropertyAccessor loadProps INFO: Using properties at /path/to/openidm/resolver/boot.properties Enter the Json value > Press ctrl-D to finish input Start data input: {"password":"myPassw0rd"} ^D -----BEGIN HASHED VALUE----- { "$crypto" : { "value" : { "algorithm" : "SHA-384", "data" : "7Caabx7d+vOZ7d3VMwdQObQJdTQ3uGOItsX5AwR4ViygUfARR/XuxRIBQt1LRq58ZOQXFwuw+3rvzK7Kld8pSg==" }, "type" : "salted-hash" } } ------END HASHED VALUE------ ``` ## `keytool` The `keytool` subcommand exports or imports secret key values. The Java `keytool` command enables you to export and import public keys and certificates but not secret or symmetric keys. The IDM `keytool` subcommand provides this functionality. Usage is as follows: ``` ./cli.sh keytool [--export, --import] alias ``` For example, to export the default IDM symmetric key, run the following command: ``` ./cli.sh keytool --export openidm-sym-default Executing ./cli.sh... Starting shell in /home/idm/openidm Use KeyStore from: /openidm/security/keystore.jceks Please enter the password: [OK] Secret key entry with algorithm AES AES:606d80ae316be58e94439f91ad8ce1c0 ``` The default keystore password is `changeit`. For security reasons, you *must* change this password in a production environment. For information about changing the keystore password, refer to [The IDM keystore](../security-guide/default-keystore.html). To import a new secret key named my-new-key, run the following command: ``` ./cli.sh keytool --import my-new-key Using boot properties at /openidm/resolver/boot.properties Use KeyStore from: /openidm/security/keystore.jceks Please enter the password: Enter the key: AES:606d80ae316be58e94439f91ad8ce1c0 ``` If a secret key with that name already exists, IDM returns the following error: ``` "KeyStore contains a key with this alias" ``` ## `validate` The `validate` subcommand validates all .json configuration files in your project's `conf/` directory. Usage is as follows: ```none ./cli.sh validate Executing ./cli.sh Starting shell in /path/to/openidm Using boot properties at /path/to/openidm/resolver/boot.properties ................................................................... [Validating] Load JSON configuration files from: [Validating] /path/to/openidm/conf [Validating] audit.json .................................. SUCCESS [Validating] authentication.json ......................... SUCCESS ... [Validating] sync.json ................................... SUCCESS [Validating] ui-configuration.json ....................... SUCCESS [Validating] ui-countries.json ........................... SUCCESS [Validating] workflow.json ............................... SUCCESS ```