Kickidler Server 1.0 for Linux - Fix SCRAM Authentication Error

Kickidler Server 1.0 for Linux - Fix SCRAM Authentication Error


1. Purpose

This article explains how to fix the PostgreSQL authentication error that may appear in Kickidler Server logs during or after Linux server installation.

The article applies to Kickidler Server 1.0 for Linux installations where PostgreSQL uses scram-sha-256 authentication, but the server component requires a compatible PostgreSQL authentication method.

2. Error Symptoms

The following error may appear in the server logs:

ERROR database connection failed: SCRAM authentication requires libpq version 10 or above

QPSQL: Unable to connect

In this state, Kickidler Server cannot authenticate to PostgreSQL and may fail to start correctly or may not be able to access the database.

3. Cause

The issue is usually related to PostgreSQL 14. By default, PostgreSQL 14 may use the scram-sha-256 authentication method.

Kickidler Server 1.0 may not be able to authenticate with this method in some Linux environments because the PostgreSQL client library used by the server component is not compatible with SCRAM authentication.

The practical fix is to switch PostgreSQL local authentication from scram-sha-256 to md5 and then reset the kickidler_node database user password so that PostgreSQL stores it in the compatible format.

IMPORTANT

Use md5 for this fix. Do not use trust for a production database unless it was explicitly approved for temporary diagnostics. The trust method disables password verification for matching connections.

4. Before You Start

Make sure the following conditions are met:

  • you have SSH or console access to the Linux server; 
  • you have sudo privileges; 
  • the server uses a systemd-based Linux distribution; 
  • PostgreSQL configuration files are located under /etc/postgresql/14/main/; 
  • the PostgreSQL database user is kickidler_node; 
  • you know the database password used by Kickidler Server. In a default installation, this password is usually scout. 

WARNING

The commands below temporarily stop Kickidler Server. During this time, the server may not receive data from agents and the web interface may be unavailable. Perform the procedure during a maintenance window if the server is used in production.

5. Create Configuration Backups

Before changing PostgreSQL configuration files, create backup copies:

sudo cp /etc/postgresql/14/main/postgresql.conf /etc/postgresql/14/main/postgresql.conf.bak.$(date +%F_%H-%M-%S)

sudo cp /etc/postgresql/14/main/pg_hba.conf /etc/postgresql/14/main/pg_hba.conf.bak.$(date +%F_%H-%M-%S)

6. Stop KickidlerNode

Stop the KickidlerNode service before changing PostgreSQL authentication settings:

sudo systemctl stop kickidlernode

Check that the service has stopped:

sudo systemctl status kickidlernode

7. Change password_encryption to md5

Open the PostgreSQL configuration file:

sudo nano /etc/postgresql/14/main/postgresql.conf

Find this line:

#password_encryption = scram-sha-256

Uncomment it and change it to:

password_encryption = md5



Save the file and exit the editor. In nano, press Ctrl+O, press Enter, then press Ctrl+X.

8. Restart PostgreSQL

Restart PostgreSQL so the new password encryption setting is loaded:

sudo systemctl restart postgresql

9. Change pg_hba.conf Authentication Method to md5

Open the PostgreSQL client authentication configuration file:

sudo nano /etc/postgresql/14/main/pg_hba.conf

Find the lines where scram-sha-256 is used for local PostgreSQL access and change the method to md5.

Example:

host all all 127.0.0.1/32 md5




Save the file and exit the editor.

NOTE

Do not change unrelated network access rules unless this is required by the administrator. PostgreSQL should not be exposed to user workstations or the Internet.

10. Reset the kickidler_node Password

After changing password_encryption to md5, reset the password for the kickidler_node PostgreSQL user. This is required so the password is stored in the compatible format.

Switch to the PostgreSQL system user:

sudo su postgres

Start the PostgreSQL interactive shell:

psql

Change the password for the kickidler_node user:

\password kickidler_node

When PostgreSQL asks for the password, enter the database password used by Kickidler Server. In a default installation, use:

scout

Exit PostgreSQL:

\q

Return to your normal shell session:

exit

11. Restart PostgreSQL and Start KickidlerNode

Restart PostgreSQL again:

sudo systemctl restart postgresql

Start KickidlerNode:

sudo systemctl start kickidlernode

12. Verify the Result

Check that PostgreSQL and KickidlerNode are running:

sudo systemctl status postgresql

sudo systemctl status kickidlernode

Then check the server logs again. The SCRAM authentication error should no longer appear.

Expected result:

  • KickidlerNode starts successfully; 
  • the server can connect to PostgreSQL; 
  • the error SCRAM authentication requires libpq version 10 or above is no longer repeated in the logs; 
  • the Kickidler Server web interface and server functions become available again. 

13. Rollback

If the server does not start after the changes, restore the configuration files from the backups created before the procedure.

Example rollback commands:

sudo systemctl stop kickidlernode

sudo cp /etc/postgresql/14/main/postgresql.conf.bak.YYYY-MM-DD_HH-MM-SS /etc/postgresql/14/main/postgresql.conf

sudo cp /etc/postgresql/14/main/pg_hba.conf.bak.YYYY-MM-DD_HH-MM-SS /etc/postgresql/14/main/pg_hba.conf

sudo systemctl restart postgresql

sudo systemctl start kickidlernode

Replace YYYY-MM-DD_HH-MM-SS with the actual timestamp from the backup file names.

14. When to Contact Technical Support

Contact Kickidler technical support if:

  • the kickidler_node PostgreSQL user does not exist; 
  • the password in the server configuration is different from the expected value; 
  • PostgreSQL does not restart after editing the configuration files; 
  • KickidlerNode still cannot connect to PostgreSQL after the procedure; 
  • the same SCRAM authentication error continues to appear in the logs. 

When contacting support, provide the following information:

  • Linux distribution and version; 
  • PostgreSQL version; 
  • the exact error text from the logs; 
  • the contents of the relevant local entries from pg_hba.conf; 
  • the current value of password_encryption in postgresql.conf; 
  • the status output for postgresql and kickidlernode.