Inspecting the LINSTOR H2 Database

In rare situations, you might need to inspect the LINSTOR® internal database. LINSTOR uses an embedded H2 database by default. This article explains how to use the H2 Console to access the LINSTOR database.

First, download the H2 Console from the H2 Database Engine website). LINSTOR uses the 1.4.197 distribution of the H2 database.

You can use the following commands on a Linux system to download and decompress the appropriate distribution.

mkdir -p /path-to/some-directory && cd /path-to/some-directory
curl -LO https://h2database.com/h2-2018-03-18.zip
unzip h2-2018-03-18.zip

Copying the LINSTOR controller database ensures that we do not accidentally alter the production controller’s database.

❗ IMPORTANT: It is always recommended to take backups of your LINSTOR controller database, especially if you are going to alter it.

If the LINSTOR controller service is currently running, temporarily stop the LINSTOR controller service on the LINSTOR controller node:

systemctl stop linstor-controller

Copy the LINSTOR controller database from the LINSTOR controller node into the H2 Console directory on the node where you downloaded the H2 Console in the previous step.

scp user@linstor-controller:/var/lib/linstor/linstordb.mv.db /path-to/some-directory/

After copying the database file, restart the LINSTOR controller if you need to resume LINSTOR operations while inspecting the LINSTOR database.

systemctl start linstor-controller

Before starting the H2 Console, you will need to configure some H2 Console server options.

First, set an environment variable to the directory where you copied the LINSTOR controller database.

export linstor_db_dir=/path-to/some-directory/

Then, add the LINSTOR database settings to the H2 Console server properties configuration in your user’s home directory:

cat << EOF >> ~/.h2.server.properties
99=LINSTOR|org.h2.Driver|jdbc\:h2\:${linstor_db_dir}linstordb|linstor
webAllowOthers=true
webPort=8082
webSSL=false
EOF

The settings above enable access to the H2 Console web UI on port 8082, from remote systems (default allows access only to localhost). If you intend to access the web UI from localhost, you can omit the webAllowOthers=true line.

Finally, from within the directory that you downloaded and decompressed the H2 Console, use Java to start the H2 Console server:

java -jar h2/bin/h2-1.4.197.jar

Open a web browser and browse to the IP address of the system running the H2 console on port 8082, for example, http://192.168.111.105:8082/.

You should be redirected to a connection prompt. If you have not previously changed the linstor user’s password within the LINSTOR controller database, the default username is linstor and the default password is linstor.

💡 TIP: If you do choose to update the linstor user’s password, or otherwise modify the credentials used to access the database, you will need to update the /etc/linstor/linstor.toml configuration with the new credentials. Examples of how to set the database username and password can be found in the LINSTOR User Guide.

Once connected, you can use SQL queries to inspect or even modify the database.

The screenshot above shows:

1. The structure of the databases and tables LINSTOR uses.
2. The SQL query editor where you write your SQL queries.
3. The results of the SQL query that was run.

Opening and interacting with the LINSTOR database directly should not be necessary for day-to-day operations. This type of interaction with the LINSTOR database is necessary for development and debugging purposes only.

Written by: MDK, 2025-06-13.

Reviewed by: MAT, 2025-06-13.