Start script

Last modified 12 Mar 2024 17:07 +01:00

What is this about…​

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

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

This page focuses directly on midpoint.sh 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 assumption that installation directory is /opt/midpoint/.

To start the application simply use

/opt/midpoint/bin/midpoint.sh start

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

/opt/midpoint/bin/start.sh

Available options

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

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

  • 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.

    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/midpoint.sh 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/midpoint.sh start
/opt/midpoint/bin/midpoint.sh start -Dfile.encoding=UTF8 -Dmidpoint.repository.database=postgresql

Purpose of the script

The script midpoint.sh 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:

midpoint.pid

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).

midpoint.out

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

midpoint.log

The application log.

Default values for the parameters

  • -Xms2048M

  • -Xmx4096M

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

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

  • -Djavax.net.ssl.trustStoreType : jceks

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

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

available environment variables

  • MP_GEN_SYSTEMD

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/midpoint.sh start

The same result will be reached using generate parameter.

/opt/midpoint/bin/midpoint.sh generate

  • MP_MP_ENTRY_POINT

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

  • MP_MEM_MAX

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.

  • MP_MEM_INIT

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 run 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.

The possibilities are not limited only to the midPoint as application. Based on the structure of the value the "target" of the changes is defined.

Example of the targeted variables:

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

  • MP_SET_server_*
    These values is related to the embedded Tomcat environment.
example for setting setting / overwriting value from config.xml
(ENV) MP_SET_midpoint_repository_database=postgresql => (JAVA_OPTS) -Dmidpoint.repository.database=postgresql
example for setting setting / overwriting value from application.yaml (Tomcat)
(ENV) MP_SET_server_port=8088 => (JAVA_OPTS) -Dserver.port=8088

  • JAVA_OPTS

JAVA_OPTS environment variable

-Xmx

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

--Xmx

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

-Xms

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

--Xms

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

-D*

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

REPO_DATABASE_TYPE

MP_SET_midpoint_repository_database

REPO_USER

MP_SET_midpoint_repository_jdbcUsername

REPO_PASSWORD_FILE

MP_SET_midpoint_repository_jdbcPassword_FILE

REPO_MISSING_SCHEMA_ACTION

MP_SET_midpoint_repository_missingSchemaAction

REPO_UPGRADEABLE_SCHEMA_ACTION

MP_SET_midpoint_repository_upgradeableSchemaAction

REPO_SCHEMA_VARIANT

MP_SET_midpoint_repository_schemaVariant

REPO_SCHEMA_VERSION_IF_MISSING

MP_SET_midpoint_repository_schemaVersionIfMissing

MP_KEYSTORE_PASSWORD_FILE

MP_SET_midpoint_keystore_keyStorePassword_FILE

REPO_PORT

N/A (see MP_SET_midpoint_repository_jdbcUrl)

REPO_HOST

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

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

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.

Was this page helpful?
YES NO
Thanks for your feedback