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

<chapter xml:id='chap-services'

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>Starting and Stopping OpenIDM</title>

<para>This chapter covers the scripts provided for starting and stopping

OpenIDM, and describes how to verify the <emphasis>health</emphasis> of a

system, that is, that all requirements are met for a successful system

startup.</para>

<section xml:id="starting-and-stopping">

<title>To Start and Stop OpenIDM</title>

<indexterm>

<primary>Starting OpenIDM</primary>

</indexterm>

<indexterm>

<primary>Stopping OpenIDM</primary>

</indexterm>

<para>By default you start and stop OpenIDM in interactive mode.</para>

<itemizedlist>

<para>To start OpenIDM interactively, open a terminal or command window,

change to the <filename>openidm</filename> directory, and run the startup

script:</para>

<listitem>

<para><command>startup.sh</command> (UNIX)</para>

</listitem>

<listitem>

<para><command>startup.bat</command> (Windows)</para>

</listitem>

</itemizedlist>

<para>The startup script starts OpenIDM, and opens an OSGi console with a

<literal>-&gt;</literal> prompt where you can issue console commands.</para>

<para>To stop OpenIDM interactively in the OSGi console, enter the

<command>shutdown</command> command.</para>

<screen>-&gt; shutdown</screen>

<orderedlist>

<para>You can also start OpenIDM as a background process on UNIX, Linux, and

Mac OS X. Follow these steps <emphasis>before starting OpenIDM for the first

time</emphasis>.</para>

<listitem>

<para>If you have already started OpenIDM, then shut down OpenIDM and

remove Felix cache files under

<filename>openidm/felix-cache/</filename>.</para>

<screen>-&gt; shutdown

...

$ rm -rf felix-cache/*</screen>

</listitem>

<listitem>

<para>Disable <literal>ConsoleHandler</literal> logging before starting

OpenIDM by editing <filename>openidm/conf/logging.properties</filename>

to set <literal>java.util.logging.ConsoleHandler.level = OFF</literal>,

and to comment out other references to <literal>ConsoleHandler</literal>,

as shown in the following excerpt.</para>

<programlisting language="ini">

# ConsoleHandler: A simple handler for writing formatted records to System.err

#handlers=java.util.logging.FileHandler, java.util.logging.ConsoleHandler

handlers=java.util.logging.FileHandler

...

# --- ConsoleHandler ---

# Default: java.util.logging.ConsoleHandler.level = INFO

java.util.logging.ConsoleHandler.level = OFF

#java.util.logging.ConsoleHandler.formatter = ...

#java.util.logging.ConsoleHandler.filter=...</programlisting>

</listitem>

<listitem>

<para>Remove the text-based OSGi console bundle,

<filename>bundle/org.apache.felix.shell.tui-<replaceable>version</replaceable>.jar</filename>.</para>

</listitem>

<listitem>

<para>Start OpenIDM in the background.</para>

<screen>$ /startup.sh &amp;

[3] 454

$ /startup.sh

Using OPENIDM_HOME: /path/to/openidm

Using OPENIDM_OPTS: -Xmx1024m

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

$</screen>

<para>Alternatively, use the <command>nohup</command> command to keep

OpenIDM running after you log out.</para>

<screen>$ nohup /startup.sh &amp;

[2] 394

$ appending output to nohup.out

$</screen>

</listitem>

</orderedlist>

<para>To stop OpenIDM running as a background process, use the

<command>shutdown.sh</command> script.</para>

<screen>$ /shutdown.sh

/shutdown.sh

Stopping OpenIDM (454)</screen>

</section>

<section xml:id="startup-configuration">

<title>Specifying the OpenIDM Startup Configuration</title>

<para>By default, OpenIDM starts up with the configuration and script files

that are located in the <filename>openidm/conf</filename> and

<filename>openidm/script</filename> directories, and with the binaries that

are in the default install location. You can launch OpenIDM with a different

configuration and set of script files, and even with a different set of

binaries, in order to test a new configuration, managed multiple different

OpenIDM projects, or to run one of the included samples.</para>

<para>The <literal>startup.sh</literal> script enables you to specify the

following elements of a running OpenIDM instance.</para>

<itemizedlist>

<listitem>

<para>project location (<literal>-p</literal>)</para>

<para>The project location specifies the configuration and default

scripts with which OpenIDM will run.

</para>

<para>If you specify the project location, OpenIDM does not try to

locate configuration objects in the default location. All configuration

objects and any artifacts that are not in the bundled defaults (such as

custom scripts) <emphasis>must</emphasis> be provided in the project

location. This includes everything that is in the default

<literal>openidm/conf</literal> and <literal>openidm/script</literal>

directories.</para>

<para>The following command starts OpenIDM with the configuration of

sample 1:</para>

<screen>$ /startup.sh -p /path/to/openidm/samples/sample1</screen>

<para>If an absolute path is not provided, the path is relative to the

system property, <literal>user.dir</literal>. If no project location is

specified, OpenIDM is launched with the default configuration in

<literal>/path/to/openidm/conf</literal>.</para>

</listitem>

<listitem>

<para>working location (<literal>-w</literal>)</para>

<para>The working location specifies the directory to which OpenIDM

writes its cache. Specifying a working location separates the project

from the cached data that the system needs to store. The working

location includes everything that is in the default

<literal>openidm/db</literal> and <literal>openidm/logs</literal>

directories.</para>

<para>The following command specifies that OpenIDM writes its cached

data to <filename>/Users/admin/openidm/storage</filename>:</para>

<screen>$ /startup.sh -w /Users/admin/openidm/storage</screen>

<para>If an absolute path is not provided, the path is relative to the

system property, <literal>user.dir</literal>. If no working location is

specified, OpenIDM writes its cached data to

<literal>openidm/db</literal> and <literal>openidm/logs</literal>.</para>

</listitem>

<listitem>

<para>startup configuration file (<literal>-c</literal>)</para>

<para>A customizable startup configuration file (named

<filename>launcher.json</filename>) enables you to specify how the OSGi

Framework is started.</para>

<para>If no configuration file is specified, the default configuration

(defined in <filename>/path/to/openidm/bin/launcher.json</filename>) is

used. The following command starts OpenIDM with an alternative startup

configuration file:</para>

<screen>$ /startup.sh -c /Users/admin/openidm/bin/launcher.json</screen>

<para>You can modify the default startup configuration file to specify

a different startup configuration.</para>

<para>The customizable properties of the default startup configuration

file are as follows:</para>

<itemizedlist>

<listitem>

<para><literal>"location" : "bundle"</literal> - resolves to the

install location. You can also load OpenIDM from a specified zip

file (<literal>"location" : "openidm.zip"</literal>) or you can

install a single jar file

(<literal>"location" : "openidm-system-2.1.jar"</literal>).</para>

</listitem>

<listitem>

<para><literal>"includes" : "**/openidm-system-*.jar"</literal> -

the specified folder is scanned for jar files relating to the system

startup. If the value of <literal>"includes"</literal> is

<literal>*.jar</literal>, you must specifically exclude any jars in

the bundle that you do not want to install, by setting the

<literal>"excludes"</literal> property.</para>

</listitem>

<listitem>

<para><literal>"start-level" : 1</literal> - specifies a start level

for the jar files identified previuosly.</para>

</listitem>

<listitem>

<para><literal>"action" : "install.start"</literal> - a

period-separated list of actions to be taken on the jar files.

Values can be one or more of

<literal>"install.start.update.uninstall"</literal>.</para>

</listitem>

<listitem>

<para><literal>"config.properties"</literal> - takes either a path to

a configuration file (relative to the project location) or a list

of configuration properties and their values. The list must be in

the format <literal>

<replaceable>"string"</replaceable>:<replaceable>"string"</replaceable>

</literal>, for example:</para>

<programlisting language="javascript">

"config.properties" :

{

"property" : "value"

},

</programlisting>

</listitem>

<listitem>

<para><literal>"system.properties"</literal> - takes either a path to

a <filename>system.properties</filename> file (relative to the project

location) or a list of system properties and their values. The list

must be in the format <literal>

<replaceable>"string"</replaceable>:<replaceable>"string"</replaceable>

</literal>, for example:</para>

<programlisting language="javascript">

"system.properties" :

{

"property" : "value"

},

</programlisting>

</listitem>

<listitem>

<para><literal>"boot.properties"</literal> - takes either a path to

a <filename>boot.properties</filename> file (relative to the project

location) or a list of boot properties and their values.The list

must be in the format <literal>

<replaceable>"string"</replaceable>:<replaceable>object</replaceable>

</literal>, for example:</para>

<programlisting language="javascript">

"boot.properties" :

{

"property" : true

},

</programlisting>

</listitem>

</itemizedlist>

</listitem>

</itemizedlist>

</section>

<section xml:id="info-service">

<title>Obtaining Information About an OpenIDM Instance</title>

<para>OpenIDM includes a customizable information service that provides

detailed information about a running OpenIDM instance. The information can

be accessed over the REST interface, under the context

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

<para>By default, OpenIDM provides the following information:</para>

<itemizedlist>

<listitem>

<para>Basic information about the health of the system.</para>

<para>This information can be accessed over REST at

<literal>http://localhost:8080/openidm/info/ping</literal>. For example:

</para>

<screen width="91"><?dbfo pgwide="1"?>$ curl

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

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

--request GET

"http://localhost:8080/openidm/info/ping"

{"state":"ACTIVE_READY","shortDesc":"OpenIDM ready"}

</screen>

<para>The information is provided by the script

<filename>openidm/bin/defaults/script/info/ping.js</filename>.</para>

</listitem>

<listitem>

<para>Information about the current OpenIDM session.</para>

<para>This information can be accessed over REST at

<literal>http://localhost:8080/openidm/info/login</literal>. For example:

</para>

<screen width="91"><?dbfo pgwide="1"?>$ curl

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

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

--request GET

"http://localhost:8080/openidm/info/ping"

{

"username":"openidm-admin",

"userid":{

"id":"openidm-admin",

"component":"internal/user"

}

} </screen>

<para>The information is provided by the script

<filename>openidm/bin/defaults/script/info/login.js</filename>.</para>

</listitem>

</itemizedlist>

<para>You can extend or override the default information that is provided by

creating your own script file and its corresponding configuration file in

<filename>openidm/conf/info-<replaceable>name</replaceable>.json</filename>.

Custom script files can be located anywhere, although a best practice is to

place them in <filename>openidm/script/info</filename>. A sample customized

script file for extending the default ping service is provided in

<filename>openidm/samples/infoservice/script/info/customping.js</filename>.

The corresponding configuration file is provided in

<filename>openidm/samples/infoservice/conf/info-customping.json</filename>.</para>

<para>The configuration file has the following syntax:</para>

<programlisting>

{

"infocontext" : "ping",

"type" : "text/javascript",

"file" : "script/info/customping.js"

}

</programlisting>

<para>The parameters in the configuration file are as follows:</para>

<itemizedlist>

<listitem>

<para><literal>"infocontext"</literal> specifies the relative name of

the info endpoint under the info context. The information can be accessed

over REST at this endpoint, for example, setting

<literal>"infocontext"</literal> to <literal>"mycontext/myendpoint"</literal>

would make the information accessible over REST at

<literal>http://localhost:8080/openidm/info/mycontext/myendpoint</literal>.

</para>

</listitem>

<listitem>

<para><literal>"type"</literal> specifies the type of the information

source. Currently, only Javascript is supported, so the type must be

<literal>"text/javascript"</literal>.</para>

</listitem>

<listitem>

<para><literal>"file"</literal> specifies the path to the Javascript

file, if you do not provide a <literal>"source"</literal> parameter.</para>

</listitem>

<listitem>

<para><literal>"source"</literal> specifies the actual Javascript, if

you have not provided a <literal>"file"</literal> parameter.</para>

</listitem>

</itemizedlist>

<para>Additional properties can be passed to the script in this configuration

file (<filename>openidm/samples/infoservice/conf/info-

<replaceable>name</replaceable>.json</filename>).</para>

<para>Script files in <filename>openidm/samples/infoservice/script/info/</filename>

have access to the following objects:</para>

<itemizedlist>

<listitem>

<para><literal>request</literal> - the request details, including the

method called and any parameters passed.</para>

</listitem>

<listitem>

<para><literal>healthinfo</literal> - the current health status of the

system.</para>

</listitem>

<listitem>

<para><literal>openidm</literal> - access to the JSON resource API.</para>

</listitem>

<listitem>

<para>Any additional properties that are defined in the configuration

file (<filename>openidm/samples/infoservice/conf/info-

<replaceable>name</replaceable>.json</filename>.)</para></listitem>

</itemizedlist>

</section>

<section xml:id="system-healthcheck">

<title>Verifying the Health of an OpenIDM System</title>

<indexterm>

<primary>healthcheck</primary>

</indexterm>

<para>Due to the highly modular, configurable nature of OpenIDM, it is often

difficult to assess whether a system has started up successfully, or whether

the system is ready and stable after dynamic configuration changes have been

made.</para>

<para>OpenIDM provides a configurable health check service that verifies

that the required modules and services for an operational system are up and

running. During system startup, OpenIDM checks that these modules and

services are available and reports on whether any requirements for an

operational system have not been met. If dynamic configuration changes are

made, OpenIDM rechecks that the required modules and services are functioning

so that system operation is monitored on an ongoing basis.</para>

<para>The health check service reports on the state of the OpenIDM system and

outputs this state to the console and to the log files. The system can be in

one of the following states:</para>

<simplelist>

<member><literal>STARTING</literal> - OpenIDM is starting up</member>

<member><literal>ACTIVE_READY</literal> - all of the specified requirements

have been met to consider the OpenIDM system ready</member>

<member><literal>ACTIVE_NOT_READY</literal> - one or more of the specified

requirements have not been met and the OpenIDM system is not considered ready

</member>

<member><literal>STOPPING</literal> - OpenIDM is shutting down</member>

</simplelist>

<para>By default, OpenIDM checks the following modules and services:</para>

<para><emphasis role="bold">Required Modules</emphasis></para>

<screen>

"org.forgerock.openicf.framework.connector-framework"

"org.forgerock.openicf.framework.connector-framework-internal"

"org.forgerock.openicf.framework.connector-framework-osgi"

"org.forgerock.openidm.audit"

"org.forgerock.openidm.core"

"org.forgerock.openidm.enhanced-config"

"org.forgerock.openidm.external-email"

"org.forgerock.openidm.external-rest"

"org.forgerock.openidm.filter"

"org.forgerock.openidm.httpcontext"

"org.forgerock.openidm.infoservice"

"org.forgerock.openidm.policy"

"org.forgerock.openidm.provisioner"

"org.forgerock.openidm.provisioner-openicf"

"org.forgerock.openidm.repo"

"org.forgerock.openidm.restlet"

"org.forgerock.openidm.smartevent"

"org.forgerock.openidm.system"

"org.forgerock.openidm.ui"

"org.forgerock.openidm.util"

"org.forgerock.commons.org.forgerock.json.resource"

"org.forgerock.commons.org.forgerock.json.resource.restlet"

"org.forgerock.commons.org.forgerock.restlet"

"org.forgerock.commons.org.forgerock.util"

"org.forgerock.openidm.security-jetty"

"org.forgerock.openidm.jetty-fragment"

"org.forgerock.openidm.quartz-fragment"

"org.ops4j.pax.web.pax-web-extender-whiteboard"

"org.forgerock.openidm.scheduler"

"org.ops4j.pax.web.pax-web-jetty-bundle"

"org.forgerock.openidm.repo-jdbc"

"org.forgerock.openidm.repo-orientdb"

"org.forgerock.openidm.config"

"org.forgerock.openidm.crypto"

</screen>

<para><emphasis role="bold">Required Services</emphasis></para>

<screen>

"org.forgerock.openidm.config"

"org.forgerock.openidm.provisioner"

"org.forgerock.openidm.provisioner.openicf.connectorinfoprovider"

"org.forgerock.openidm.external.rest"

"org.forgerock.openidm.audit"

"org.forgerock.openidm.policy"

"org.forgerock.openidm.managed"

"org.forgerock.openidm.script"

"org.forgerock.openidm.crypto"

"org.forgerock.openidm.recon"

"org.forgerock.openidm.info"

"org.forgerock.openidm.router"

"org.forgerock.openidm.scheduler"

"org.forgerock.openidm.scope"

"org.forgerock.openidm.taskscanner"

</screen>

<para>You can replace this list, or add to it, by adding the following lines

to the <filename>openidm/conf/boot/boot.properties</filename> file:</para>

<simplelist>

<member><literal>"openidm.healthservice.reqbundles"</literal> - overrides

the default required bundles. Bundles are specified as a list of symbolic

names, separated by commas.</member>

<member><literal>"openidm.healthservice.reqservices"</literal> - overrides

the default required services. Services are specified as a list of symolic

names, separated by commas.</member>

<member><literal>"openidm.healthservice.additionalreqbundles"</literal> -

specifies required bundles (in addition to the default list). Bundles are

specified as a list of symbolic names, separated by commas.</member>

<member><literal>"openidm.healthservice.additionalreqservices"</literal> -

specifies required services (in addition to the default list). Services are

specified as a list of symbolic names, separated by commas.</member>

</simplelist>

<para>By default, OpenIDM gives the system ten seconds to start up all

the required bundles and services, before the system readiness is assessed.

Note that this is not the total start time, but the time required to complete

the service startup after the framework has started. You can change this

default by setting the value of the <literal>servicestartmax</literal>

property (in miliseconds) in the

<filename>openidm/conf/boot/boot.properties</filename> file. This example

sets the startup time to five seconds.</para>

<screen>openidm.healthservice.servicestartmax=5000</screen>

<para>The health check service works in tandem with the scriptable information

service. For more information see <xref linkend="info-service" />.</para>

</section>

</chapter>