Skip to end of metadata
Go to start of metadata

Clustering / high availability can be achieved by setting up two midPoint nodes working against common midPoint repository.

In order to do this, it is necessary to set a couple of parameters in midPoint configuration.

An example, when using H2 database:

Main difference from the default configuration is that now the H2 database cannot be run "embedded", i.e. in a subprocess of servlet container hosting midPoint WAR. It has to be run as a standalone process. The configuration (<repository>) reflects this. In this case, we expect H2 to be run at port 6000 (see <jdbcUrl>). Other parameters (LOCK_MODE=1;DB_CLOSE_ON_EXIT=FALSE;LOCK_TIMEOUT=10000) are necessary for midPoint repository to work correctly. For more information on configuring the repository, please see this document.

Besides the repository, there is a need to configure task manager a bit. Typically, the following parameters have to be set:

ParameterDescription
clusteredDetermines if the installation is running in clustered (failover) mode. Default is false. If you need clustering/failover, set this to true.
jdbcUrl

If you are using H2, you have to set up use different database parameters from those used by midPoint repository. And, because MVCC mode is to be enabled, task manager has to use a database instance different from the one used by the repository.

If you are using database other than H2, you may skip setting special jdbcUrl in the <taskManager> configuration. The jdbcUrl from repository config will be used. As a result, Quartz tables will be stored in the same database instance as midPoint tables.

dataSourceUses specified data source to obtain DB connections. (See Repository Configuration).
jmxUsername, jmxPasswordCredentials used for JMX communication among cluster nodes. Default values are shown in example above, but we strongly recommend changing at least the JMX password. Currently, all nodes should be accessible using the same credentials.

Other task manager database settings (e.g. jdbc username and password, driver class name, hibernate dialect) are taken by default from <repository> configuration, but, of course, they may be overriden in task manager configuration. 

Important: if there are more nodes sharing a repository, all of them must have parameter "clustered" set to true. Otherwise, tasks will not be scheduled correctly. (midPoint will disable scheduling tasks on non-conformant nodes, i.e. on non-clustered nodes that are parts of such a system.) The best way how to ensure this is to have common config file. But if that's not possible or practical, make sure that all nodes have the same settings.

Important: ensure your system time is synchronized across all node members (using NTP or similar service), otherwise strange behaviour may occur such as reconciliation restart on different nodes.

Java system properties

Mainly because of JMX limitations, some parameters have to be set up via Java system properties. In the following we expect the Oracle JRE is used.

midpoint.nodeId

This is an identifier of the local node. It is not part of the midPoint configuration, because we assume that this configuration file will be shared among cluster members. The default value is: DefaultNode. However, when running in clustered mode, there is no default, and this property must be explicitly specified.

midpoint.jmxHostName

Host name on which this node wants to be contacted (via JMX) by other nodes in cluster. (It will be announced to other nodes via Node record in repository.) Usually not necessary to specify, as the default is the current host IP address.

com.sun.management.jmxremote.port

This is the port on which JMX agent will listen. It must be specified for clustered mode, because JMX is used to query status of individual nodes and to manage them (start/stop scheduler, stop tasks on that node). And, if you test a clustering/failover configuration (more midPoint nodes) on a single machine, be sure to set this parameter to different values for individual midPoint nodes. Otherwise, you will get "java.net.BindException: Address already in use: JVM_Bind" exception on tomcat startup.

com.sun.management.jmxremote.ssl

Whether SSL will be used for JMX communication. For sample installations it can be set to false, however, for production use we recommend setting it to true (alongside other SSL-related JMX properties, see http://docs.oracle.com/javase/1.5.0/docs/guide/management/agent.html#remote.

com.sun.management.jmxremote.password.file and com.sun.management.jmxremote.access.file

Names of the password and access files for JMX authentication and authorization. E.g. d:\midpoint\config\jmxremote.password, d:\midpoint\config\jmxremote.access. Examples of these files are in the samples/jmx directory in SVN.

Beware, the jmxremote.password file must be readable only to its owner (i.e. user who starts the tomcat), otherwise the JVM refuses to start. In Windows, you typically have to stop inheriting permissions to this file, and manually remove all entries that grant access to persons other than the owner.

Example

NodeA (in catalina.bat)


NodeB
(in catalina.bat)

(Note: the jmx port is set to 20002 just to allow running both nodes on a single machine. If you are sure they will not be run on a single machine, we recommend setting the port to the same value, just for simplicity.)

(Note: when you have firewall, please also set com.sun.management.jmxremote.rmi.port to the same port as com.sun.management.jmxremote.port)

midPoint configuration (repo and task manager parts)

 

 

Do not forget to start H2 database independently of both nodes. In this case, it is expected to listen on port 6000. To do that, you can use e.g. this command line

 

Cluster infrastructure configuration

For some types of information (e.g. reports) to be accessible by each cluster peer present in the cluster, midpoint needs to have an intra cluster http url pattern specified. This should be the HTTP/HTTPS pattern which is used by midpoint nodes to communicate with each others. The pattern is in fact an URL prefix pointing to the root URL of the application. The pattern is specified in the system configuration object as present in the example bellow.

Example:

Troubleshooting

The following message(s) may appear in idm.log if there is a problem with JMX password:

 

In that case, double-check your JMX passwords (in config.xml and in jmx.remote.password files) in all instances.

The following message(s) may appear in idm.log if there is problem with firewall between IDM nodes:

Please note that it seems that JMX communication needs more than the JMX port specified in Tomcat startup configuration (in this fragment, 8123)! I resolved the problem by simply allowing all TCP communication between the nodes. I will update this solution after I find a better one (smile)

The following message may appear if your clock is not synchronized between midPoint nodes:

 

 

  • No labels