Navigation Tree

Ninja

Last modified 20 Jul 2026 06:39 UTC

Ninja is a command-line tool bundled with midPoint that can communicate directly with the repository database. This makes it particularly useful for administrative and recovery tasks. Because it works directly with the repository, it can be used even when the web UI or REST API are unavailable. Typical use cases include recovering from configuration issues or object data corruption that prevent midPoint from starting, as well as restoring access when the built-in administrator account is locked out.

Since Ninja operates directly on the repository layer, it bypasses the model component. As a result, authorizations are not enforced, changes are not audited, and model-level processing is skipped. While this makes Ninja a powerful recovery tool, it also means that it should be used with caution.

In addition to object import and export, Ninja provides several administrative and maintenance commands. These include listing keys stored in the keystore, re-encrypting objects with a new encryption key, validating the database schema, resetting user passwords, and unlocking user accounts.

Since midPoint 4.8 (also in 4.4.6, 4.7.2 and later), commands and options names realigned:

All command and option names are kebab cased.
File output is now -o, --output
-O, --overwrite for all commands.

Running Ninja

Ninja can be started either by using the bundled shell/batch scripts or as a standalone Java application.

Both methods provide the same functionality. The bundled scripts simplify the startup process by automatically locating the midPoint home directory and preparing the runtime environment.

Bundled scripts

The bundled ninja.sh (Linux/macOS) and ninja.bat (Windows) scripts provide the simplest way to run Ninja. They automatically configure Ninja and start the ninja.jar application.

The scripts are located in the <midpoint>/bin directory. In the following examples, <midpoint> denotes the root directory of the midPoint installation.

For commands that communicate directly with the repository, Ninja needs access to the midPoint home directory. It uses the config.xml file located in the midPoint home directory to obtain the repository configuration.

By default, the bundled scripts determine the midPoint home directory automatically:

If the MIDPOINT_HOME environment variable is defined, its value is used.
Otherwise, the scripts use the default <midpoint>/var directory.

Example command with $MIDPOINT_HOME environment variable directly defined in the command line

MIDPOINT_HOME=/var/other-mp-home <midpoint>/bin/ninja.sh [general options] [command] [command options]

Alternatively, the location of the midPoint home directory can be specified explicitly using the -m option.

Example using the -m option

<midpoint>/bin/ninja.sh -m /var/other-mp-home [general options] [command] [command options]

When using a standalone Ninja container, initialize the midPoint home directory before running repository commands:

midpoint.sh init-native

This allows Ninja to locate the required configuration files (such as config.xml) and initialize the repository layer.

This step is not required when running Ninja from an existing midPoint container, because the midPoint home directory has already been initialized.

Once the midPoint home directory is located, Ninja reads the repository configuration from config.xml. If the file contains the JDBC URL, username, and password, these values are used automatically.

If config.xml contains only a datasource definition, the connection details must be provided explicitly using:

-U - JDBC URL
-u - JDBC username
-p, or -P - JDBC password

These options can also be used to override the values specified in config.xml.

Using Ninja as a standalone JAR application

Ninja can also be executed directly as a standalone JAR application without using the bundled shell or batch scripts.

When running Ninja this way, the location of the midPoint home directory must be specified explicitly using the -m option.

General command syntax

java -jar ninja.jar -m <midpoint_home> [general options] [connection options] [command] [command options]

Example overriding JDBC connection details specified in config.xml

java -jar ninja.jar -m /opt/midpoint-home -U jdbc:postgresql://localhost:5432/testdb -u testuser -p testpassword export -t UserType -o /tmp/user-types.xml

Using Ninja with databases other than PostgreSQL

If you are using a different database (for example, Oracle or Microsoft SQL Server), you must obtain an appropriate JDBC driver and provide it to Ninja.

When running Ninja using the bundled scripts, specify the path to the JDBC driver JAR file using the -j option.
Example using a custom JDBC driver with bundled scripts
```
<midpoint>/bin/ninja.sh \
  -j /path/to/jdbc-driver.jar \
  [general options] [connection options] [command] [command options]
```
When running Ninja as a standalone JAR application, specify the JDBC driver using the -Dloader.path JVM option.
Example using a custom JDBC driver with standalone Ninja
```
java -Dloader.path=/path/to/jdbc-driver.jar \
  -jar ninja.jar \
  [general options] [connection options] [command] [command options]
```

FAQ

Can I use Ninja from a midPoint 4.8.* distribution with a deployment running midPoint 4.4.*?

No, Ninja 4.8 internally uses a repository (DB) implementation from midPoint 4.8. MidPoint 4.4.* has differences in the DB schema compared to midPoint 4.8. Technically it is possible to run Ninja 4.4.7 against midPoint 4.4.2, for example, since the DB schema did not change between these versions. However, this is not recommended and it is not supported.

Why raw (`-r`, `--raw`) option is needed when exporting objects?

The raw option will tell Ninja to export objects together with their definitions if needed. These definitions are used to import objects back to midPoint. For more information, see Export.

How multithreading works?

Ninja uses multithreading for exporting and importing objects. Ninja will create a thread pool with a number of threads.

When reading objects from midPoint, Ninja will create queries that will split the data by object type (e.g., users, roles, shadows, …). On top of this, shadow objects are also split by resource OID. Each query and query result is then processed by a separate thread.

When importing objects to midPoint, Ninja reads the file with objects in a single queue, and adds objects to the midPoint repository in parallel.