<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-install'

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

xmlns:xlink='http://www.w3.org/1999/xlink'>

<title>Installing OpenIDM Services</title>

<para>

This chapter covers the tasks required to install and start OpenIDM.

</para>

<section xml:id="before-you-start">

<title>Before You Run OpenIDM</title>

<para>

This section covers what you need to know before running OpenIDM.

</para>

<section xml:id="java-prerequisites">

<title>Java Environment</title>

<indexterm>

<primary>Java</primary>

<secondary>Requirements</secondary>

</indexterm>

<para>

This release of OpenIDM requires Java Development Kit 6 or Java Development

Kit 7. ForgeRock recommends the most recent update of Java 6 or 7 to ensure

that you have the latest security fixes.

</para>

<para>

In addition, on Windows systems, you must set the

<literal>JAVA_HOME</literal> environment variable to point to the root of a

valid Java installation. The following steps indicate how to set the

<literal>JAVA_HOME</literal> environment variable on Windows Server 2008 R2.

Adjust the steps for your specific environment.

</para>

<itemizedlist>

<listitem>

<para>

Locate your JRE Installation Directory. If you have not changed the

installation path for the Java Runtime Environment during installation, it

will be in a directory under <literal>C:\Program Files\Java\</literal>.

</para>

</listitem>

<listitem>

<para>

Select Start > Control Panel > System and Security > System.

</para>

</listitem>

<listitem>

<para>

Click Advanced System Settings.

</para>

</listitem>

<listitem>

<para>

Click Environment Variables.

</para>

</listitem>

<listitem>

<para>

Under System Variables, click New.

</para>

</listitem>

<listitem>

<para>

Enter the Variable name (<literal>JAVA_HOME</literal>) and set the

Variable value to the JRE installation directory, for example

<literal>C:\Program Files\Java\jre7</literal>.

</para>

</listitem>

<listitem>

<para>

Click OK.

</para>

</listitem>

</itemizedlist>

</section>

<section xml:id="application-container-prerequisites">

<title>Application Container</title>

<indexterm>

<primary>Application container</primary>

<secondary>Requirements</secondary>

</indexterm>

<para>

OpenIDM services run in an OSGi container with an embedded Servlet

container, and an embedded noSQL database. By default the OSGi container is

Apache Felix. The default Servlet container is Jetty. For OpenIDM

${docTargetVersion}, the only supported configuration is running

the services in Apache Felix and Jetty.

</para>

</section>

</section>

<section xml:id="installing-openidm">

<title>Installing and Running OpenIDM</title>

<para>

Follow the procedures in this section to install and run OpenIDM.

</para>

<procedure xml:id="install-openidm">

<title>To Install OpenIDM Services</title>

<indexterm>

<primary>Installing</primary>

</indexterm>

<para>

Follow these steps to install OpenIDM.

</para>

<step>

<para>

Make sure you have an appropriate version of Java installed.

</para>

<screen><userinput>$ java -version</userinput>

<computeroutput>

java version "1.6.0_24"

Java(TM) SE Runtime Environment (build 1.6.0_24-b07-334)

Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02-334, mixed mode)</computeroutput>

</screen>

<para>

Check the release notes for Java requirements in the chapter, <link

xlink:href="release-notes#chap-before-you-install"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Before You

Install OpenIDM Software</citetitle></link>.

</para>

</step>

<step>

<indexterm>

<primary>Downloading</primary>

</indexterm>

<itemizedlist>

<para>

Download OpenIDM from one of the following locations:

</para>

<listitem>

<para>

<link xlink:show="new" xlink:href="http://www.forgerock.com/download-stack/">

Enterprise Downloads</link> has the latest stable, supported release of

OpenIDM and the other products in the ForgeRock identity stack.

</para>

</listitem>

<listitem>

<para>

<link xlink:show="new" xlink:href="http://forgerock.org/openidm.html">

Builds</link> includes the nightly build and the OpenIDM agents. Note

that this is the working version of the trunk and should not be used in

a production environment.

</para>

</listitem>

<listitem>

<para>

<link xlink:show="new" xlink:href="http://forgerock.org/openidm-archive.html">

Archives</link> includes the stable builds for all previous releases of

OpenIDM.

</para>

</listitem>

</itemizedlist>

</step>

<step>

<para>

Unpack the contents of the .zip file into the install location.

</para>

<screen><userinput>$ cd /path/to

$ unzip ~/Downloads/openidm-${docTargetVersion}.zip

</userinput>

<computeroutput>

...

inflating: openidm/connectors/scriptedsql-connector-${openicfBundleVersion}.jar

inflating: openidm/bin/felix.jar

inflating: openidm/bin/openidm.jar</computeroutput>

</screen>

</step>

<step performance="optional">

<para>

By default, OpenIDM listens for HTTP and HTTPS connections on ports 8080

and 8443, respectively. To change the default port, edit the

<filename>/path/to/openidm/conf/boot/boot.properties</filename> file. For

more information, see <link xlink:href="integrators-guide#appendix-ports-used"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Ports Used</citetitle></link>

in the <citetitle>Integrator's Guide</citetitle>.

</para>

</step>

<step performance="optional">

<indexterm>

<primary>Repository database</primary>

<secondary>Requirements</secondary>

</indexterm>

<para>Before running OpenIDM in production, replace the default OrientDB

repository provided for evaluation with a JDBC repository.</para>

<para>See the chapter on <link xlink:href="install-guide#chap-repository"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Installing

a Repository For Production</citetitle></link> for details.</para>

</step>

</procedure>

<procedure xml:id="run-openidm">

<title>To Start OpenIDM Services</title>

<indexterm>

<primary>Starting OpenIDM</primary>

</indexterm>

<para>Follow these steps to run OpenIDM interactively.</para>

<para>To run OpenIDM as a background process, see <link

xlink:href="integrators-guide#chap-services"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Starting and

Stopping OpenIDM</citetitle></link> in the <citetitle>Integrator's

Guide</citetitle>.</para>

<step>

<para>Start the Felix container, load all OpenIDM services, and start a

command shell to allow you to manage the container.</para>

<stepalternatives>

<step>

<para>Start OpenIDM (UNIX).</para>

<screen><userinput>$ /startup.sh</userinput>

<computeroutput>

Using OPENIDM_HOME: /path/to/openidm

Using OPENIDM_OPTS: -Xmx1024m -Xms1024m

Using LOGGING_CONFIG:

-Djava.util.logging.config.file=/path/to/openidm/conf/logging.properties

Using boot properties at /path/to/openidm/conf/boot/boot.properties

OpenIDM version "${docTargetVersion}" (revision: XXXX)

-> OpenIDM ready

</computeroutput>

</screen>

</step>

<step>

<para>Start OpenIDM (Windows).</para>

<screen><userinput>C:\&gt; cd \path\to\openidm

C:\&gt; startup.bat

</userinput>

<computeroutput>

"Using OPENIDM_HOME: \path\to\openidm"

"Using OPENIDM_OPTS: -Xmx1024m -Xms1024m -Dfile.encoding=UTF-8"

"Using LOGGING_CONFIG:

-Djava.util.logging.config.file=\path\to\openidm\conf\logging.properties"

Using boot properties at \path\to\openidm\conf\boot\boot.properties

OpenIDM version "${docTargetVersion}" (revision: XXXX)

-> OpenIDM ready

-&gt;

</computeroutput>

</screen>

</step>

</stepalternatives>

<para>At the resulting <literal>-&gt;</literal> prompt, you can enter

commands such as <command>help</command> for usage, or

<command>ps</command> to view the bundles installed. To see a list of all

the OpenIDM core services and their states, enter the following

command.</para>

<screen width="87"><userinput>-&gt; scr list</userinput>

<computeroutput>

Id State Name

[ 12] [active ] org.forgerock.openidm.endpoint

[ 13] [active ] org.forgerock.openidm.endpoint

[ 14] [active ] org.forgerock.openidm.endpoint

[ 15] [active ] org.forgerock.openidm.endpoint

[ 16] [active ] org.forgerock.openidm.endpoint

[ 17] [active ] org.forgerock.openidm.endpoint

[ 23] [unsatisfied ] org.forgerock.openidm.info

[ 27] [active ] org.forgerock.openidm.provisioner.openicf.connectorinfoprovider

[ 35] [active ] org.forgerock.openidm.ui.simple

[ 29] [active ] org.forgerock.openidm.restlet

[ 3] [active ] org.forgerock.openidm.repo.orientdb

[ 7] [active ] org.forgerock.openidm.scope

[ 5] [active ] org.forgerock.openidm.audit

[ 32] [active ] org.forgerock.openidm.schedule

[ 2] [unsatisfied ] org.forgerock.openidm.repo.jdbc

[ 31] [active ] org.forgerock.openidm.workflow

[ 9] [active ] org.forgerock.openidm.managed

[ 28] [active ] org.forgerock.openidm.provisioner.openicf

[ 22] [active ] org.forgerock.openidm.health

[ 26] [active ] org.forgerock.openidm.provisioner

[ 0] [active ] org.forgerock.openidm.config.starter

[ 34] [active ] org.forgerock.openidm.taskscanner

[ 20] [active ] org.forgerock.openidm.external.rest

[ 6] [active ] org.forgerock.openidm.router

[ 33] [active ] org.forgerock.openidm.scheduler

[ 19] [unsatisfied ] org.forgerock.openidm.external.email

[ 11] [active ] org.forgerock.openidm.sync

[ 25] [active ] org.forgerock.openidm.policy

[ 8] [active ] org.forgerock.openidm.script

[ 10] [active ] org.forgerock.openidm.recon

[ 4] [active ] org.forgerock.openidm.http.contextregistrator

[ 1] [active ] org.forgerock.openidm.config

[ 18] [active ] org.forgerock.openidm.endpointservice

[ 30] [unsatisfied ] org.forgerock.openidm.servletfilter

[ 24] [active ] org.forgerock.openidm.infoservice

[ 21] [active ] org.forgerock.openidm.authentication

-&gt;

</computeroutput>

</screen>

<para>A default startup does not include certain configurable services,

which will indicate an <literal>unsatisfied</literal> state until they

are included in the configuration. As you work through the sample

configurations described later in this guide, you will notice that these

services are active.</para>

<para>Startup errors and messages are logged to the console by default.

You can also view these messages in the log files at

<filename>/path/to/openidm/logs</filename>.</para>

</step>

<step>

<para>Alternatively, you can manage the container and services from the

Felix administration console.</para>

<itemizedlist>

<para>Use these hints to connect to the console.</para>

<listitem>

<para>Default Console URL: <link xlink:show="new"

xlink:href='https://localhost:8443/system/console' /></para>

</listitem>

<listitem>

<para>Default user name: <literal>admin</literal></para>

</listitem>

<listitem>

<para>Default password: <literal>admin</literal></para>

</listitem>

</itemizedlist>

<itemizedlist>

<para>Some basic hints on using the Felix administration console

follow.</para>

<listitem>

<para>Select the Components tab to see OpenIDM core services and their

respective states.</para>

</listitem>

<listitem>

<para>Select the Shell tab to access the <literal>-&gt;</literal>

prompt.</para>

</listitem>

<listitem>

<para>Select the System Information tab to stop or restart the

container.</para>

</listitem>

</itemizedlist>

</step>

</procedure>

<procedure xml:id="stop-openidm">

<title>To Stop the OpenIDM Services</title>

<indexterm>

<primary>Stopping OpenIDM</primary>

</indexterm>

<step>

<para>You can stop OpenIDM Services from the <literal>-&gt;</literal>

prompt, or through the Felix console.</para>

<stepalternatives>

<step>

<para>Either enter the <command>shutdown</command> command at the

<literal>-&gt;</literal> prompt.</para>

<screen>-&gt; shutdown

...

$</screen>

</step>

<step>

<para>Or click Stop on the System Information tab of the Felix console,

by default <link xlink:show="new"

xlink:href='http://localhost:8080/system/console' />.</para>

<para>This stops the Servlet container as well, and the console is

no longer accessible.</para>

</step>

<step>

<para>

On Unix systems, you can stop OpenIDM by using the

<command>shutdown.sh</command> script, located in the

<filename>/path/to/openidm</filename> directory.

</para>

<screen><userinput>$ /shutdown.sh</userinput>

<computeroutput>/shutdown.sh

Stopping OpenIDM (31391)</computeroutput></screen>

</step>

</stepalternatives>

</step>

</procedure>

</section>

<section xml:id="first-steps-with-rest">

<title>To Get Started With the OpenIDM REST Interface</title>

<indexterm>

<primary>Getting started</primary>

</indexterm>

<para>

OpenIDM provides RESTful access to users in the OpenIDM repository. To

access the OpenIDM repository over REST, you can use a browser-based REST

client, such as the

<link xlink:href="https://chrome.google.com/webstore/detail/simple-rest-client/fhjcajmcbmldlhcimfajhfbgofnpcjmb">

Simple REST Client</link> for Chrome, or <link xlink:href="https://addons.mozilla.org/en-US/firefox/addon/restclient/">

RESTClient</link> for Firefox. Alternatively you can use the

<command>curl</command> command-line utility that is included with most

operating systems. For more information about <command>curl</command>, see

<link xlink:href="https://github.com/bagder/curl" />.

</para>

<para>

OpenIDM is accessible over the regular and secure HTTP ports of the Jetty

Servlet container, 8080 and 8443.

</para>

<para>

If you want to run <command>curl</command> over the secure port, 8443, you

must either include the <command>--insecure</command> option, or follow the

instructions shown in

<link xlink:show="new" xlink:href="integrators-guide#rest-over-https"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Restrict

REST Access to the HTTPS Port</citetitle></link>. You can use those

instructions with the self-signed certificate that is generated when

OpenIDM starts, or with a <filename>*.crt</filename> file provided by a

certificate authority.

</para>

<para>

In numerous cases, <command>curl</command> commands to the secure port

are depicted with a <literal>--cacert self-signed.crt</literal> option.

Instructions for creating that <filename>self-signed.crt</filename> file

are shown in the aforementioned section on <link xlink:show="new"

xlink:href="integrators-guide#rest-over-https"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Restrict

REST Access to the HTTPS Port</citetitle></link>.

</para>

<para>

If you would rather use <command>curl</command> to connect to the regular

HTTP port, omit the <literal>--cacert self-signed.crt</literal> file and

point to a regular Jetty HTTP URL such as

<literal>http://localhost:8080/openidm/...</literal>.

</para>

<note>

<para>

All RESTful command line examples in this guide, as depicted with

<command>curl</command>, are based on the default configuration of

OpenIDM. If you change configuration files in directories such as

<filename>openidm/conf</filename> and <filename>openidm/script</filename>,

you might need to modify the RESTful commands to reflect those changes.

</para>

<para>

Most of the examples in this guide use client-assigned IDs when creating

resources, as it makes the examples easier to read.

</para>

<para>

In general, server-assigned UUIDs are better in production, as they can be

generated easily in clustered environments.

</para>

</note>

<procedure xml:id="first-rest-steps">

<step>

<para>Access the following URL to obtain the JSON representation of all

users in the OpenIDM repository.</para>

<screen>$ curl \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

http://localhost:8080/openidm/managed/user/?_queryId=query-all-ids</screen>

<para>When you first install OpenIDM with an empty repository, no users

exist.</para>

</step>

<step>

<para>Create a user <literal>joe</literal> by sending a RESTful POST.</para>

<para>The following <command>curl</command> commands create the user

<literal>joe</literal> in the repository.</para>

<stepalternatives>

<step>

<para>Create <literal>joe</literal> (UNIX).</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "Content-Type: application/json" \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request POST \

--data '{ \

"userName":"joe", \

"givenName":"joe", \

"sn":"smith", \

"mail":"joe@example.com", \

"telephoneNumber":"555-123-1234", \

"password":"TestPassw0rd", \

"description":"My first user", \

"_id":"joe" \

}' \

https://localhost:8443/openidm/managed/user?_action=create</userinput>

<computeroutput>

{

"userName": "joe",

"stateProvince": "",

"postalAddress": "",

"effectiveAssignments": {},

"roles": [

"openidm-authorized"

],

"telephoneNumber": "555-123-1234",

"password": {

"$crypto": {

"value": {

"key": "openidm-sym-default",

"iv": "gTcveNaZdSHE1qeBgcmzRw==",

"cipher": "AES/CBC/PKCS5Padding",

"data": "X9sCuuvNwSbblxdqS65qxw=="

},

"type": "x-simple-encryption",

}

},

"effectiveRoles": [

"openidm-authorized"

],

"givenName": "joe",

"address2": "",

"lastPasswordAttempt": "Tue Feb 25 2014 18:03:40 GMT-0800 (PST)",

"passwordAttempts": "0",

"sn": "smith",

"mail": "joe@example.com",

"country": "",

"city": "",

"_rev": "1",

"lastPasswordSet": "",

"postalCode": "",

"accountStatus": "active",

"description": "My first user",

"_id":"joe"

} </computeroutput>

</screen>

</step>

<step>

<para>Create <literal>joe</literal> (Windows).</para>

<screen>C:\&gt; curl ^

--cacert self-signed.crt ^

--header "Content-Type: application/json" ^

--header "X-OpenIDM-Username: openidm-admin" ^

--header "X-OpenIDM-Password: openidm-admin" ^

--request POST ^

--data "{ ^

\"userName\":\"joe\", ^

\"givenName\":\"joe\", ^

\"sn\":\"smith\", ^

\"mail\":\"joe@example.com\", ^

\"telephoneNumber\":\"555-123-1234\", ^

\"password\":\"TestPassw0rd\", ^

\"description\":\"My first user\" ^

\"_id\":\"joe\" ^

}" ^

https://localhost:8443/openidm/managed/user?_action=create</screen>

</step>

</stepalternatives>

</step>

<step>

<para>Fetch the newly created user from the repository with a RESTful

GET.</para>

<screen><userinput>$ curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

https://localhost:8443/openidm/managed/user/joe

</userinput>

<computeroutput>

{

"effectiveAssignments": {},

"effectiveRoles": [

"openidm-authorized"

],

"stateProvince": "",

"userName": "joe",

"postalAddress": "",

"givenName": "joe",

"address2": "",

"lastPasswordAttempt": "Tue Feb 25 2014 18:13:03 GMT-0800 (PST)",

"passwordAttempts": "0",

"sn": "smith",

"mail": "joe@example.com",

"_rev": "1",

"_id": "joe",

"country": "",

"city": "",

"lastPasswordSet": "",

"postalCode": "",

"description": "My first user",

"accountStatus": "active",

"telephoneNumber": "555-123-1234",

"roles": [

"openidm-authorized"

]

}</computeroutput></screen>

</step>

<step>

<para>

Notice that more attributes are returned for user <literal>joe</literal>

than the attributes you added in the previous step. The additional

attributes are added by a script named

<literal>onCreate-user-set-default-fields.js</literal> that is triggered

when a new user is created. For more information, see <link

xlink:href="integrators-guide#managed-object-configuration"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Managed Object

Configuration</citetitle></link> in the <citetitle>Integrator's

Guide</citetitle>.

</para>

<para>

When you create a user some attributes might be required by the policy

associated with that user. These are listed in the

<filename>conf/policy.json</filename> file.

</para>

</step>

</procedure>

<section xml:id="rest-output-format">

<title>Format REST Output for Readability</title>

<para>

With all <command>curl</command>-based REST calls, OpenIDM returns the JSON

object all on one line.

</para>

<para>

Without a bit of help, the JSON output is formatted all on one line. One

example is shown below, and it is difficult to read:

</para>

<screen>

<computeroutput>

{"mail":"joe@example.com","sn":"smith","passwordAttempts":"0",

"lastPasswordAttempt":"Mon Apr 14 2014 11:13:37 GMT-0800 (GMT-08:00)",

"address2":"","givenName":"joe","effectiveRoles":["openidm-authorized"],

"password":{"$crypto":{"type":"x-simple-encryption","value":{"data":

"OBFVL9cG8uaLoo1N+SMJ3g==","cipher":"AES/CBC/PKCS5Padding","iv":

"7rlV4EwkwdRHkt19F8g22A==","key":"openidm-sym-default"}}},"country":"",

"city":"","_rev":"1","lastPasswordSet":"","postalCode":"","_id":"joe3",

"description":"My first user","accountStatus":"active","telephoneNumber":

"555-123-1234","roles":["openidm-authorized"],"effectiveAssignments":{},

"postalAddress":"","stateProvince":"","userName":"joe3"}

</computeroutput>

</screen>

<para>

At least two options are available to clean up this output.

</para>

<para>

The standard way to format JSON output is with a JSON parser such as

<link xlink:href="http://stedolan.github.io/jq/">jq</link>. You would

"pipe" the output of a REST call to <command>jq</command>, as follows:

</para>

<screen>$<userinput> curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user/joe" \

| jq .

</userinput>

</screen>

<para>

The ForgeRock REST API includes an optional <literal>_prettyPrint</literal>

request parameter. The default value is <literal>false</literal>. To

use the ForgeRock REST API to format output, add a parameter such as

<literal>?_prettyPrint=true</literal> or

<literal>&amp;_prettyPrint=true</literal>, depending on whether it is added

to the end of an existing request parameter. In this case, the following

command would return formatted output:

</para>

<screen>$<userinput> curl \

--cacert self-signed.crt \

--header "X-OpenIDM-Username: openidm-admin" \

--header "X-OpenIDM-Password: openidm-admin" \

--request GET \

"https://localhost:8443/openidm/managed/user/joe?_prettyPrint=true"

</userinput>

</screen>

<para>

Note that most command-line examples in this guide do not show this

parameter, although the output is formatted for readability.

</para>

</section>

</section>

</chapter>