OpenIDM includes a basic command-line interface that provides a number of utilities for managing the OpenIDM instance.
All of the utilities are subcommands of the cli.sh
(UNIX) or cli.bat (Windows) scripts. To use the utilities,
you can either run them as subcommands, or launch the cli
script first, and then run the utility. For example, to run the
encrypt utility on a UNIX system:
$ cd /path/to/openidm $ ./cli.sh Using boot properties at /openidm/conf/boot/boot.properties openidm# encrypt ....
or
$ cd /path/to/openidm $ ./cli.sh encrypt ...
By default, the command-line utilities run with the properties defined
in /path/to/openidm/conf/boot/boot.properties.
The startup and shutdown scripts are not discussed in this chapter. For information about these scripts, see Starting and Stopping OpenIDM.
The following sections describe the subcommands and their use. Examples assume that you are running the commands on a UNIX system. For Windows systems, use cli.bat instead of cli.sh.
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 OpenIDM instance.
OpenIDM must be running when you execute this command.
Usage is as follows:
$ ./cli.sh configexport /export-location
For example:
$ ./cli.sh configexport /tmp/conf
Configuration objects are exported, as .json files,
to the specified directory. Configuration files that are present in this
directory are renamed as backup files, with a timestamp, for example,
audit.json.2012-12-19T12-00-28.bkp, and are not
overwritten. The following configuration objects are exported:
The internal repository configuration (repo.orientdb.json
or repo.jdbc.json)
The log configuration (audit.json)
The authentication configuration (authentication.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)
The synchronization mapping configuration (sync.json
)
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 policy configuration (policy.json)
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 OpenIDM 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.
If you include the --replaceAll parameter, the
command 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.
Usage is as follows:
$ ./cli.sh configimport [--replaceAll] /import-location
For example:
$ ./cli.sh configimport --replaceAll /tmp/conf
Configuration objects are imported, as .json files,
from the specified directory to the conf directory. The
configuration objects that are imported are outlined in the corresponding
export command, described in the previous section.
The configureconnector subcommand generates a configuration for an OpenICF connector.
Usage is as follows:
$ ./cli.sh configureconnector connector-name
Select the type of connector that you want to configure. The following example configures a new XML connector.
$ ./cli.sh configureconnector myXmlConnector Using boot properties at /openidm/conf/boot/boot.properties Dec 11, 2012 10:35:37 AM org.restlet.ext.httpclient.HttpClientHelper start INFO: Starting the HTTP client 0. CSV File Connector version 1. LDAP Connector version 2. org.forgerock.openicf.connectors.scriptedsql.ScriptedSQLConnector version 3. XML Connector version 4. Exit Select [0..4]: 3 Edit the configuration file and run the command again. The configuration was saved to /openidm/temp/provisioner.openicf-myXmlConnector.json
The basic configuration is saved in a file named
/openidm/temp/provisioner.openicf-.
Edit the connector-name.jsonconfigurationProperties parameter in this file to
complete the connector configuration. For an XML connector, you can use the
schema definitions in sample 0 for an example configuration.
"configurationProperties" : {
"xmlFilePath" : "samples/sample0/data/resource-schema-1.xsd",
"createFileIfNotExists" : false,
"xsdFilePath" : "samples/sample0/data/resource-schema-extension.xsd",
"xsdIcfFilePath" : "samples/sample0/data/xmlConnectorData.xml"
},
For more information about the connector configuration properties, see Configuring Connectors.
When you have modified the file, run the configureconnector command again so that OpenIDM can pick up the new connector configuration.
$ ./cli.sh configureconnector myXmlConnector
Using boot properties at /openidm/conf/boot/boot.properties
Configuration was found and picked up from:
/openidm/temp/provisioner.openicf-myXmlConnector.json
Dec 11, 2012 10:55:28 AM org.restlet.ext.httpclient.HttpClientHelper start
INFO: Starting the HTTP client
...
You can also configure connectors over the REST interface. For more information, see Creating Default Connector Configurations.
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 OpenIDM repository. The encrypted value is output to standard output and provides details of the cryptography key that is used to encrypt the data.
Usage is as follows:
$ ./cli.sh encrypt [-j] string
The -j option specifies that the string to be
encrypted is a JSON object. 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, any special characters, for example
quotation marks, must be escaped.
The following example encrypts a normal string value:
$ ./cli.sh encrypt mypassword
Using boot properties at /openidm/conf/boot/boot.properties
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Activating cryptography service of type: JCEKS provider:
location: security/keystore.jceks
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-sym-default
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-localhost
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-local-openidm-forgerock-org
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: CryptoService is initialized with 3 keys.
-----BEGIN ENCRYPTED VALUE-----
{
"$crypto" : {
"value" : {
"iv" : "M2913T5ZADlC2ip2imeOyg==",
"data" : "DZAAAM1nKjQM1qpLwh3BgA==",
"cipher" : "AES/CBC/PKCS5Padding",
"key" : "openidm-sym-default"
},
"type" : "x-simple-encryption"
}
}
------END ENCRYPTED VALUE------
The following example encrypts a JSON object. The input string must be a valid JSON object.
$ ./cli.sh encrypt -j {\"password\":\"myPassw0rd\"}
Using boot properties at /openidm/conf/boot/boot.properties
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Activating cryptography service of type: JCEKS provider:
location: security/keystore.jceks
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-sym-default
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-localhost
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-local-openidm-forgerock-org
Oct 23, 2012 2:00:03 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: CryptoService is initialized with 3 keys.
-----BEGIN ENCRYPTED VALUE-----
{
"$crypto" : {
"value" : {
"iv" : "M2913T5ZADlC2ip2imeOyg==",
"data" : "DZAAAM1nKjQM1qpLwh3BgA==",
"cipher" : "AES/CBC/PKCS5Padding",
"key" : "openidm-sym-default"
},
"type" : "x-simple-encryption"
}
}
------END ENCRYPTED VALUE------
The following example prompts for a JSON object to be encrypted. In this case, you need not escape the special characters.
$ ./cli.sh encrypt -j
Using boot properties at /openidm/conf/boot/boot.properties
Enter the Json value
> Press ctrl-D to finish input
Start data input:
{"password":"myPassw0rd"}
^D
Oct 23, 2012 2:37:56 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Activating cryptography service of type: JCEKS provider:
location: security/keystore.jceks
Oct 23, 2012 2:37:56 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-sym-default
Oct 23, 2012 2:37:56 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-localhost
Oct 23, 2012 2:37:56 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: Available cryptography key: openidm-local-openidm-forgerock-org
Oct 23, 2012 2:37:56 PM org.forgerock.openidm.crypto.impl.CryptoServiceImpl activate
INFO: CryptoService is initialized with 3 keys.
-----BEGIN ENCRYPTED VALUE-----
{
"$crypto" : {
"value" : {
"iv" : "6e0RK8/4F1EK5FzSZHwNYQ==",
"data" : "gwHSdDTmzmUXeD6Gtfn6JFC8cAUiksiAGfvzTsdnAqQ=",
"cipher" : "AES/CBC/PKCS5Padding",
"key" : "openidm-sym-default"
},
"type" : "x-simple-encryption"
}
}
------END ENCRYPTED VALUE------
The keytool subcommand exports or imports private key values.
The Java keytool command enables you to export and import public keys and certificates, but not private keys. The OpenIDM keytool subcommand provides this functionality.
Usage is as follows:
./cli.sh keytool [--export, --import] alias
For example, to export the default OpenIDM symmetric key, run the following command:
$ ./cli.sh keytool --export openidm-sym-default Using boot properties at /openidm/conf/boot/boot.properties 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. You
should change this password after installation.
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/conf/boot/boot.properties Use KeyStore from: /openidm/security/keystore.jceks Please enter the password: Enter the key: AES:606d80ae316be58e94439f91ad8ce1c0
If a secret key of that name already exists, OpenIDM returns the following error:
"KeyStore contains a key with this alias"
The validate subcommand validates all .json
configuration files in the openidm/conf/ directory.
Usage is as follows:
$ ./cli.sh validate Using boot properties at /openidm/conf/boot/boot.properties ................................................................... [Validating] Load JSON configuration files from: [Validating] /openidm/conf [Validating] audit.json .................................. SUCCESS [Validating] authentication.json ......................... SUCCESS [Validating] endpoint-getavailableuserstoassign.json ..... SUCCESS [Validating] endpoint-getprocessesforuser.json ........... SUCCESS [Validating] endpoint-gettasksview.json .................. SUCCESS [Validating] endpoint-securityQA.json .................... SUCCESS [Validating] endpoint-siteIdentification.json ............ SUCCESS [Validating] endpoint-usernotifications.json ............. SUCCESS [Validating] managed.json ................................ SUCCESS [Validating] policy.json ................................. SUCCESS [Validating] process-access.json ......................... SUCCESS [Validating] provisioner.openicf-ldap.json ............... SUCCESS [Validating] provisioner.openicf-xml.json ................ SUCCESS [Validating] repo.orientdb.json .......................... SUCCESS [Validating] router.json ................................. SUCCESS [Validating] schedule-recon.json ......................... SUCCESS [Validating] schedule-reconcile_systemXmlAccounts_managedUser.json SUCCESS [Validating] scheduler.json .............................. SUCCESS [Validating] sync.json ................................... SUCCESS [Validating] ui-configuration.json ....................... SUCCESS [Validating] ui-countries.json ........................... SUCCESS [Validating] ui-secquestions.json ........................ SUCCESS [Validating] workflow.json ............................... SUCCESS