chap-cli.xml revision 245d622535c32563b59ef5027b1171167ba9b451
<?xml version="1.0" encoding="UTF-8"?>
<!--
! CCPL HEADER START
!
! This work is licensed under the Creative Commons
! Attribution-NonCommercial-NoDerivs 3.0 Unported License.
! To view a copy of this license, visit
! or send a letter to Creative Commons, 444 Castro Street,
! Suite 900, Mountain View, California, 94041, USA.
!
! You can also obtain a copy of the license at
! See the License for the specific language governing permissions
! and limitations under the License.
!
! If applicable, add the following below this CCPL HEADER, with the fields
! enclosed by brackets "[]" replaced with your own identifying information:
! Portions Copyright [yyyy] [name of copyright owner]
!
! CCPL HEADER END
!
! Copyright 2011-2012 ForgeRock AS
!
-->
<chapter xml:id='chap-cli'
xmlns='http://docbook.org/ns/docbook'
version='5.0' xml:lang='en'
xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'
xmlns:xlink='http://www.w3.org/1999/xlink'
xmlns:xinclude='http://www.w3.org/2001/XInclude'>
<title>OpenIDM Command-Line Interface</title>
<para>OpenIDM includes a basic command-line interface that provides a number
of utilities for managing the OpenIDM instance.</para>
you can either run them as subcommands, or launch the <command>cli</command>
script first, and then run the utility. For example, to run the
<command>encrypt</command> utility on a UNIX system:</para>
$ /cli.sh
openidm# encrypt ....
</screen>
<para>or</para>
$ /cli.sh encrypt ...
</screen>
<para>By default, the command-line utilities run with the properties defined
<para>The startup and shutdown scripts are not discussed in this chapter. For
information about these scripts, see <link xlink:href="integrators-guide#chap-services"
Stopping OpenIDM</citetitle></link>.</para>
<para>The following sections describe the subcommands and their use. Examples
assume that you are running the commands on a UNIX system. For Windows
</para>
<section xml:id="cli-configexport">
<title>configexport</title>
<para>The <command>configexport</command> 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.</para>
<para>OpenIDM must be running when you execute this command.</para>
<para>Usage is as follows:</para>
<screen>
</screen>
<para>For example:</para>
<para>Configuration objects are exported, as <filename>.json</filename> files,
to the specified directory. Configuration files that are present in this
directory are renamed as backup files, with a timestamp, for example,
overwritten. The following configuration objects are exported:</para>
<itemizedlist>
<listitem>
</listitem>
<listitem>
</listitem>
<listitem>
</filename>)</para>
</listitem>
<listitem>
</para>
</listitem>
<listitem>
</filename>)</para>
</listitem>
<listitem>
</para>
</listitem>
<listitem>
</para>
</listitem>
<listitem>
<para>Any configured schedules (<filename>schedule-*.json</filename>)
</para>
</listitem>
<listitem>
</filename>)</para>
</listitem>
<listitem>
<para>If workflows are defined, the configuration of the workflow engine
</listitem>
<listitem>
<para>Any configuration files related to the user interface
(<filename>ui-*.json</filename>)</para>
</listitem>
<listitem>
<para>The configuration of any custom endpoints
(<filename>endpoint-*.json</filename>)</para>
</listitem>
<listitem>
</listitem>
</itemizedlist>
</section>
<section xml:id="cli-configimport">
<title>configimport</title>
<para>The <command>configimport</command> 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.</para>
<para>The command updates the existing configuration from the
<replaceable>import-location</replaceable> over the OpenIDM REST interface.
By default, if configuration objects are present in the
<replaceable>import-location</replaceable> and not in the existing
configuration, these objects are added. If configuration objects are present
in the existing location but not in the
<replaceable>import-location</replaceable>, these objects are left untouched
in the existing configuration.</para>
<para>If you include the <literal>--replaceAll</literal> parameter, the
command wipes out the existing configuration and replaces it with the
configuration in the <replaceable>import-location</replaceable>. Objects in
the existing configuration that are not present in the
<replaceable>import-location</replaceable> are deleted.</para>
<para>Usage is as follows:</para>
<screen>
</screen>
<para>For example:</para>
<screen>
</screen>
<para>Configuration objects are imported, as <literal>.json</literal> files,
from the specified directory to the <filename>conf</filename> directory. The
configuration objects that are imported are outlined in the corresponding
export command, described in the previous section.</para>
</section>
<section xml:id="cli-configureconnector">
<title>configureconnector</title>
<para>The <command>configureconnector</command> subcommand generates a
configuration for an OpenICF connector.</para>
<para>Usage is as follows:</para>
</screen>
<para>Select the type of connector that you want to configure. The following
example configures a new XML connector.
</para>
INFO: Starting the HTTP client
0. CSV File Connector version 1.1.0.1-SNAPSHOT
1. LDAP Connector version 1.1.0.1-SNAPSHOT
3. XML Connector version 1.1.0.1-SNAPSHOT
4. Exit
Select [0..4]: 3
Edit the configuration file and run the command again. The configuration was
</screen>
<para>The basic configuration is saved in a file named
<filename>/openidm/temp/provisioner.openicf-<replaceable>connector-name</replaceable>.json</filename>.
Edit the <literal>configurationProperties</literal> 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.</para>
<programlisting language="javascript">
"configurationProperties" : {
"createFileIfNotExists" : false,
},
</programlisting>
<para>For more information about the connector configuration properties, see
<link xlink:href="integrators-guide#openicf-provisioner-conf"
>Configuring Connectors</citetitle></link>.</para>
<para>When you have modified the file, run the
<command>configureconnector</command> command again so that OpenIDM can pick
up the new connector configuration.</para>
INFO: Starting the HTTP client
...
</screen>
<para>You can also configure connectors over the REST interface. For more
information, see <link xlink:href="integrators-guide#connector-wiz"
>Creating Default Connector Configurations</citetitle></link>.</para>
</section>
<section xml:id="cli-encrypt">
<title>encrypt</title>
<para>The <command>encrypt</command> 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.</para>
<para>Usage is as follows:</para>
<screen>
</screen>
<para>The <literal>-j</literal> 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.</para>
<para>The following example encrypts a normal string value:</para>
<screen>
$ /cli.sh encrypt mypassword
INFO: Activating cryptography service of type: JCEKS provider: location: security/keystore.jceks
INFO: Available cryptography key: openidm-sym-default
INFO: Available cryptography key: openidm-localhost
INFO: Available cryptography key: openidm-local-openidm-forgerock-org
INFO: CryptoService is initialized with 3 keys.
-----BEGIN ENCRYPTED VALUE-----
{
"$crypto" : {
"value" : {
"iv" : "M2913T5ZADlC2ip2imeOyg==",
"data" : "DZAAAM1nKjQM1qpLwh3BgA==",
"key" : "openidm-sym-default"
},
"type" : "x-simple-encryption"
}
}
------END ENCRYPTED VALUE------
</screen>
<para>The following example encrypts a JSON object. The input string must be
a valid JSON object.</para>
<screen>
$ /cli.sh encrypt -j {\"password\":\"myPassw0rd\"}
INFO: Activating cryptography service of type: JCEKS provider: location: security/keystore.jceks
INFO: Available cryptography key: openidm-sym-default
INFO: Available cryptography key: openidm-localhost
INFO: Available cryptography key: openidm-local-openidm-forgerock-org
INFO: CryptoService is initialized with 3 keys.
-----BEGIN ENCRYPTED VALUE-----
{
"$crypto" : {
"value" : {
"iv" : "M2913T5ZADlC2ip2imeOyg==",
"data" : "DZAAAM1nKjQM1qpLwh3BgA==",
"key" : "openidm-sym-default"
},
"type" : "x-simple-encryption"
}
}
------END ENCRYPTED VALUE------
</screen>
<para>The following example prompts for a JSON object to be encrypted. In
this case, you need not escape the special characters.</para>
<screen>
$ /cli.sh encrypt -j
Enter the Json value
> Press ctrl-D to finish input
Start data input:
{"password":"myPassw0rd"}
^D
INFO: Activating cryptography service of type: JCEKS provider: location: security/keystore.jceks
INFO: Available cryptography key: openidm-sym-default
INFO: Available cryptography key: openidm-localhost
INFO: Available cryptography key: openidm-local-openidm-forgerock-org
INFO: CryptoService is initialized with 3 keys.
-----BEGIN ENCRYPTED VALUE-----
{
"$crypto" : {
"value" : {
"iv" : "6e0RK8/4F1EK5FzSZHwNYQ==",
"data" : "gwHSdDTmzmUXeD6Gtfn6JFC8cAUiksiAGfvzTsdnAqQ=",
"key" : "openidm-sym-default"
},
"type" : "x-simple-encryption"
}
}
------END ENCRYPTED VALUE------
</screen>
</section>
<section xml:id="cli-keytool">
<title>keytool</title>
<indexterm>
<primary>Keytool</primary>
</indexterm>
<para>The <command>keytool</command> subcommand exports or imports
private key values.</para>
<para>The Java <command>keytool</command> command enables you to export and
import public keys and certificates, but not private keys. The OpenIDM
<command>keytool</command> subcommand provides this functionality.</para>
<para>Usage is as follows:</para>
</command>
<para>For example, to export the default OpenIDM symmetric key, run the
following command:</para>
<screen>$ /cli.sh keytool --export openidm-sym-default
Please enter the password:
[OK] Secret key entry with algorithm AES
AES:606d80ae316be58e94439f91ad8ce1c0
</screen>
<para>The default keystore password is <literal>changeit</literal>. You
should change this password after installation.</para>
<para>To import a new secret key named <replaceable>my-new-key</replaceable>,
run the following command:</para>
<screen>$ /cli.sh keytool --import my-new-key
Please enter the password:
Enter the key:
AES:606d80ae316be58e94439f91ad8ce1c0
</screen>
<para>If a secret key of that name already exists, OpenIDM returns the
following error:</para>
<screen>"KeyStore contains a key with this alias"</screen>
</section>
<section xml:id="cli-validate">
<title>validate</title>
<indexterm>
<primary>Configuration</primary>
<secondary>Validating</secondary>
</indexterm>
<para>The <command>validate</command> subcommand validates all .json
<para>Usage is as follows:</para>
<screen>
$ /cli.sh validate
...................................................................
[Validating] Load JSON configuration files from:
[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
</screen>
</section>
</chapter>