start script

Last modified 14 Sep 2021 15:02 +02:00
The page is still in draft and the content is changing (mainly new information is being added).

What is this about…​

There is folder bin contaning, and in the midpoint home directory (default is /opt/midpoint/ ). is a wrapper to adding parameter start so <home dir>/bin/ start. is wrapper to adding parameter stop so <home dir>/bin/ stop.

This page have focus direclty on script which is covering what is needed to run the application.

Basic usage

At this place I will make assupmtion of home directory to be /opt/midpoint/

To start the application simply use

/opt/midpoint/bin/ start

Alternatively you can use "wrapper" while all the mentioned information here is applicable the same way


Advanced usage

In some situation the default is not acceptable or simply you need to be sure about the state.

example of explicit set of file encoding and database backend type
export MP_SET_file_encoding=UTF8
export MP_SET_midpoint_repository_database=postgresql
/opt/midpoint/bin/ start

Alternatively you can use other way - the result will be the same but the information will be processed different way. In this approach all the values has be provided in one variable or as a parameter :

export JAVA_OPTS="-Dfile.encoding=UTF8 -Dmidpoint.repository.database=postgresql"
/opt/midpoint/bin/ start
/opt/midpoint/bin/ start -Dfile.encoding=UTF8 -Dmidpoint.repository.database=postgresql

Purpose of the script

The script is written to handle process of the starting and stoping the midpoint as an application. There is necessary to set some variables and options to have proper working application. As an example we need to know home directory for the appliaction or classpath for the necessary classes (libraries). It is also handling PID file which is used to prevent unwanted new instance of the application while there is already one instance which is running.

There is also option to generate definition for the systemd service which will have all the parameters based on the current setting like you are running the application manually using this script.

PID file
PID file is the file where the PID (Process ID) is stored during the start of the application. Once there is request for the application start the script check existence of the PID file and in case it exists it make a test if the process with given PID exists.
This approach tries to prevent unwanted start of the application in case the instance is already running in background - daemonized.

Default "elements" for the start

There are few things which should be ready before we can sucesfully run the application.

<home directory>/log

The directory contain log files and PID file. The count and content of the file depends on the application setting. By default there may be 3 files:

PID file containg the process ID of the running midpoint to prevent unwanted parallel start (e.g. the network port to listen would be occupied).


The log file containg the output before application itself - catalina output.


The application log.

Default values for the parameters

  • -Xms2048M

  • -Xmx4096M

  • -Dpython.cachedir : ${MIDPOINT_HOME}/tmp

  • : ${MIDPOINT_HOME}/keystore.jceks

  • : jceks

  • -Dmidpoint.home : derived from the location (usually /opt/midpoint )

This is the defaults defined in the script. For usual configuration it not require to do any changes.

available environment variables


In case this variable is defined and it is not empty (e.g. MP_GEN_SYSTEMD=1) the systemd service definition is generated to the STDOUT based on the current environment (like the midpoint would be started) and then exit. By the redirecting of the output the systemd definition can be created and used to for automatic start of the midpoint application directly by the systemd.

variable can be provided directly in command line
MP_GEN_SYSTEMD=1 /opt/midpoint/bin/ start

The entry point can be used to copy some file before the system start. It is usable mainly with container approach like Docker.


Alias for JAVA_OPTS variable -Xmx[0-9]. It may be usefull especially in case the "simply" key=value syntax would be prefered to the complex set of values in one variable.


Alias for JAVA_OPTS variable -Xms[0-9]. It may be usefull especially in case the "simply" key=value syntax would be prefered to the complex set of values in one variable.

  • MP_SET_*

To make the passing the variable for java easier there has been set "mapping" for the environment variables starting with MP_SET_. The result will be -D* paramteres in JAVA_OPTS which is already passed to java process. The benefit is in maintaining configuration mainly for midpoint runnig in the containers where passing additional argument mean list all of them and not only new one. With this mapping it is easier to maintain or even generate the configuration for the container instance.

By the processing MP_SET_ "prefix" is removed and for the rest there is replaced _ with . (dot). The is exception _FILE which is handled. The prefix -D is added and the final result is added to the JAVA_OPTS variable which is used for the starting.

(ENV) MP_SET_midpoint_repository_database=postgresql ⇒ (JAVA_OPTS) -Dmidpoint.repository.database=postgresql

JAVA_OPTS environment variable


-Xmx[0-9] - Maximum memory. If not set the Default values for the parameters is unsed unless --Xmx is set.


Ignore Default values for the parameters for Xmx. The Java default value would be used (may differ with Java version)


-Xms[0-9] - Start / Init memory. If not set the Default values for the parameters is unsed unless --Xms is set.


Ignore Default values for the parameters for Xms. The Java default value would be used (may differ with Java version)


Next to other JAVA environment or application parameter -D* can be used to override config.xml parameters. The structure of the "key" in config.xml hierarchy delimited by the dot.

backwards compatible variables

This parameters has been mentioned historicaly in some scenarios and may be deprecated in the future. At this moment it is still regognized and properly processed.

former parameter current equivalent


















N/A (see MP_SET_midpoint_repository_jdbcUrl)


N/A (see MP_SET_midpoint_repository_jdbcUrl)

In this section there is available sample definition related to the specific environment.

The sample consists following environment variables:

  • MP_SET_midpoint_repository_initializationFailTimeout=60000

  • MP_SET_file_encoding=UTF8

  • MP_SET_midpoint_logging_alt_enabled=true


export MP_SET_midpoint_repository_initializationFailTimeout=60000
export MP_SET_file_encoding=UTF8
export MP_SET_midpoint_logging_alt_enabled=true


ENV MP_SET_midpoint_repository_initializationFailTimeout=60000 \
  MP_SET_file_encoding=UTF8 \

kubernets (yaml syntax)

  - name: MP_SET_midpoint_repository_initializationFailTimeout
    value: 60000
  - name: MP_SET_file_encoding
    value: UTF8
  - name: MP_SET_midpoint_logging_alt_enabled
    value: true

Docker compose

  - MP_SET_midpoint_repository_initializationFailTimeout=60000
  - MP_SET_file_encoding=UTF8
  - MP_SET_midpoint_logging_alt_enabled=true

more details for some features

entry point

In some situation it is not possible to directly mount some information to the midpoint structure (home directory). As an example may be post initial objects where once the object is processed the suffix .done is added to the name (after extension). This is normal and expected situation but in some scenario it is not what we want to realize.

The example of this situation is docker environment. Once we create container (instance of the image) we may need to re-process the post initial objects to get the environment to the specific state. In case we would attach the objects in read-only mode the processing will fail as the objects are expected to be writable. Once it is mounted as external volume, with the first processing the name is changed and in case of new instance of image the objects seems to be already processed even it was done in previous instance…​

The solution may be to use "entry point" which will look for the directory and the files located there are copied to the corresponding structure in the midpoint’s home directory. The result is writable copy of the object so the midpoint has full control over it and the objects can be re-use with the new instance of the container.

The file which is processing is looked in the midpoint’s home directory for the same name or the name with .done suffix. The result is that only new files are copied and once the file is found in the midpoint’s home direcotry it is skipped.

To use this feature there is available the environment parameter MP_ENTRY_POINT. Once it is set the "scan" is done before the regular start is initiated so it may be suitable even for the objects like schema extensions.