Start script

Last modified 23 Nov 2021 09:36 +01:00

What is this about…​

There is folder bin contaning, and in the midpoint installation directory (default is /opt/midpoint/).

Script is a wrapper for adding parameter start so <install-dir>/bin/ start. is wrapper to adding parameter stop so <install-dir>/bin/ stop.

This page focuses directly on script which is covering what is needed to run the application.

Do not confuse installation directory that contains the binaries and scripts (normally extracted from the distribution archive) with midPoint home directory that is important for the running application, containing initial configuration and logs.

Basic usage

At this place I will make assupmtion that installation directory is /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


Available options

  • start
    Start the application. There is "alias" available as

  • stop
    Stop the application. There is "alias" available as

  • generate
    Generate systemd service definition based on current setting (incl. MP_SET_* variable). After the definition is generated the script exit with exit code 0 (no other action like start or stop). The same result could be reached by using MP_GEN_SYSTEMD variable

  • container
    The similar operation like start but with focus on container environment - foreground run (do not daemonize the process), no PID handling

  • init-native
    Focused on containerized environment. Prepared mainly for generating init structure for native repository.
    This feature is better described on dedicated doc page.
    It can be used for:

    • SQL init structure for native repository

    • generate PW for the DB connection

    • prepare "basic" config.xml with native repository requirements

    • generate password for keystore or save "default" one to the file

    • generate keystore with the option to import certificate for the purpose of the checking certificates for the SSL / TLS connection(s).

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 midpoint.home directory for the application 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. Other option offer to start midpoint in foreground which is useful in case of container environments.

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 successfully 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 contains 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 contains 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 <install-dir>/var.

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 same result will be reached using generate parameter.

/opt/midpoint/bin/ generate

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 directory it is skipped.

The usage cover everything what is located in any subfolder of home directory. It is including also schema or icf-connectors folder.

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.

The example is available on the doc page dedicated to Native repository in docker environment.