Start script

Last modified 27 Jun 2025 10:39 +02:00
Table of Contents

This page describes the midpoint.sh script that is used to manage the midPoint server in environments where it is deployed as a standalone application.

Basic Usage

The midpoint.sh script handles starting and stopping the midPoint application.

The script is located in the midPoint installation directory (/opt/midpoint by default).

The bin folder of the midPoint installation directory also contains the following wrapper scripts for midpoint.sh:

  • start.sh - Starts midPoint by adding the start argument to midpoint.sh.

  • stop.sh - Stops midPoint by adding the stop argument to midpoint.sh.

The midpoint.sh script takes the following arguments:

Argument Description

start

Starts the application. This works the same as the start.sh script.

stop

Stops the application. This works the same as the stop.sh script.

generate

Generates the systemd service definition based on the current setting (including the MP_SET_* variables). After the definition is generated, the script exits with the exit code 0, i.e. there is no other action such as start or stop. You can achieve the same result by using the MP_GEN_SYSTEMD variable.

container

This is similar to the start argument, however, the application is run in the foreground, the process is not daemonized, and there is no PID handling. This is useful in containerized environments.

init-native

Initializes the native repository schema in containerized environments.

It can be used to:
* Initialize the SQL database structure for the native repository.
* Generate a password for the DB connection. * Prepare a "basic" config.xml file with native repository requirements. * Generate a password for the keystore or save the default password to the file. * Generate the keystore with the option to import a certificate for the purpose of checking certificates for the SSL / TLS connections.

To start the application, use:

<midPoint_installation_directory>/bin/midpoint.sh start

Using the wrapper, you can start the application with:

<midPoint_installation_directory>/bin/start.sh
Do not confuse the installation directory which contains the binaries and scripts (normally extracted from the distribution archive) with the midPoint home directory that is important for the running application and that contains the initial configuration and logs.

Log Directory

The log directory is located in the midPoint home directory. It contains log files and a PID file. The number of log files and their content depends on the application setting.

By default, there are 3 files:

  • midpoint.pid - The PID file contains the process ID of the running midPoint to prevent unwanted parallel midPoint instances. For example, this prevents situations when the network port used to listen is occupied.

  • midpoint.out - The log file contains the output before the application itself starts logging (Catalina output).

  • midpoint.log - The application log.

PID file
The PID file (Process ID) prevents starting new instances of the application while there already are other daemonized instances running in the background.
It is stored during the start of the application. Once there is a request for the application start, the script checks for the existence of the PID file, and if it exists, it tests if the process with the given PID exists.

Start Script Defaults

The midpoint.sh script contains some pre-configured options that cover the usual configuration. However, you may want to customize some variables and options:

Without modifications, the midpoint.sh script will start the application with the following defaults:

  • -Xms2048M

  • -Xmx4096M

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

  • -Djavax.net.ssl.trustStore : ${MIDPOINT_HOME}/keystore.jceks

  • -Djavax.net.ssl.trustStoreType : jceks

  • -Dmidpoint.home: <install-dir>/var - This is derived from the midpoint.sh location.

Advanced Usage

If you need other than default values, or you want to be more in control, you can configure environment variables to customize the application start.

Available Environment Variables

The following environment variables can be used to customize your application start:

  • MP_GEN_SYSTEMD - If this variable is defined and is not empty (e.g. MP_GEN_SYSTEMD=1), the systemd service definition is generated to the STDOUT based on the current environment (as if midPoint was started), and then the program is exited. By redirecting the output, the systemd definition can be created and used for an automatic start of the midPoint application directly by the systemd.

    The variable can be provided directly in the command line:

    MP_GEN_SYSTEMD=1 /opt/midpoint/bin/midpoint.sh start

    The same result will be reached by using the generate parameter.

    /opt/midpoint/bin/midpoint.sh generate

  • MP_ENTRY_POINT - Defines an entry point which copies files before the system start. It is used mainly in containerized environments such as Docker.

  • MP_MEM_MAX - Sets the maximum heap size. It is an alias for the JAVA_OPTS variable -Xmx[0-9]. It can be useful especially if the "simple" key=value syntax is preferred to using complex sets of values in one variable.

  • MP_MEM_INIT - Sets the initial heap size. It is an alias for the JAVA_OPTS variable -Xms[0-9]. It can be useful especially if the "simple" key=value syntax is preferred to using complex sets of values in one variable.

  • MP_SET_* - To pass environmental variables to Java more easily, there is a "mapping" for variables starting with MP_SET_. This results in -D parameters in the JAVA_OPTS variable which is already passed to Java. This is beneficial mostly for midPoint run in a container where if you want to pass an additional argument, you need to list all of the already used arguments. With this mapping, it is easier to maintain or even generate the configuration for the container instance.

    In processing, the MP_SET_ "prefix" is removed, and any following "_" (underscores) are replaced with "." (dots).
    "_FILE" is a handled exception. The prefix -D is added, and the final result is then added to the JAVA_OPTS variable which is used for starting the application.

    The possibilities are not limited only to midPoint as an application. The target is defined by the structure of the value.

    For example, you can target the following variables:

    • MP_SET_midpoint_* - These values are related to the settings located in the config.xml file (application related).

    • MP_SET_server_* - These values are related to the embedded Tomcat environment.
    Example overwriting a config.xml value
    (ENV) MP_SET_midpoint_repository_database=postgresql => (JAVA_OPTS) -Dmidpoint.repository.database=postgresql
    Example overwriting an application.yaml (Tomcat) value
    (ENV) MP_SET_server_port=8088 => (JAVA_OPTS) -Dserver.port=8088

  • JAVA_OPTS - Passes options to the JVM.

    • -Xmx[0-9] - Defines the maximum heap size. If not used, the midPoint default values apply (unless --Xmx is set).

    • --Xmx - Ignores the midPoint default values for Xmx, and uses Java defaults instead (these may differ in various Java versions).

    • -Xms[0-9] - Defines the initial heap size. If not used, the midPoint default values apply (unless --Xms is set).

    • --Xms - Ignores the midPoint default values for Xms, and uses Java defaults instead (these may differ in various Java versions).

    • -D* - In addition to other JAVA environment variables, you can use this parameter to override the config.xml parameters. The structure of the "key" in the config.xml hierarchy is delimited by "." (dot).

Using Custom Configuration

There are several ways in which you can start your midPoint instance with a custom configuration. See the examples below:

  • Explicit variable assignment - For example, the following defines file encoding and the backend database type:

    export MP_SET_file_encoding=UTF8
export MP_SET_midpoint_repository_database=postgresql
/opt/midpoint/bin/midpoint.sh start

  • Combined environment variable

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

  • In-line command line parameters

    /opt/midpoint/bin/midpoint.sh start -Dfile.encoding=UTF8 -Dmidpoint.repository.database=postgresql

Example

This shows you a sample definition for a specific environment with the following environment variables:

  • MP_SET_midpoint_repository_initializationFailTimeout=60000

  • MP_SET_file_encoding=UTF8

  • MP_SET_midpoint_logging_alt_enabled=true

Bash

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

Dockerfile

ENV MP_SET_midpoint_repository_initializationFailTimeout=60000 \
  MP_SET_file_encoding=UTF8 \
  MP_SET_midpoint_logging_alt_enabled=true

Kubernets (YAML syntax)

env:
  - 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

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

Entry Point

Using the MP_ENTRY_POINT environment property, you can ensure that midPoint has access to data that cannot be mounted directly to the midPoint structure.

In some situations, it is not possible to mount data directly to the midPoint structure, i.e. to the home directory. For example, this is the case with post initial objects where, once an object is processed, the .done suffix is added to its name (after extension). While this is normal procedure, it may be undesired.

In Docker, once you create a container (an instance of an image), you may need to re-process the post initial objects to get the environment to a specific state. If you wanted to attach the objects in the read-only mode, the processing would fail as the objects are expected to be writable. Once you mount them as an external volume, their names are already changed, i.e. the .done suffix was added during the first processing. In case you are creating a new instance of an image, the objects seem to have already been processed, even though that was done in the previous instance.

To solve this, you can use an "entry point" which will look for a directory, and copy files from that directory to a corresponding structure in the midPoint’s home directory. The result is a writable copy of the object which gives midPoint full control. You can then re-use those objects in a new instance of the container.

When a file is being processed, the system searches for a file with the same name with the .done suffix. When it finds one, it skips the original file. This ensures that only new files are copied.

This covers all subfolders of the home directory, including also the schema and the icf-connectors folder. Additionally, the "scan" is performed before the regular start is initiated which makes it convenient also for objects like schema extensions.

Was this page helpful?
YES NO
Thanks for your feedback