Troubleshooting and help

If access to the Relution system administrator account has been lost and the password cannot be reset using the configured email address, it is also possible to reset the password from the database. This procedure requires write access to the database server and Relution’s database.

The password should first be reset via the Forgot your password? link before the database route is attempted. This option should only serve as a last resort.

To reset the password, a connection to the database is first established via the command line or an administration tool. Then the SQL script that is appropriate for the database server is run. The script sets a new password for the user admin in the system organization, resets the counter of failed logins and reactivates the account if it was locked after too many failed attempts.

The prefix {noop} marks a plain-text password. Until the first login, the new password is therefore stored unencrypted in the database. On the first login, Relution automatically stores it as an Argon2 hash. The password should then be changed in the portal. If multi-factor authentication is set up for the account, the second factor is still requested after the reset.

Microsoft SQL Server and MySQL are no longer supported by Relution. Switching to MariaDB is described under Migration from MSSQL to MariaDB →.

PostgreSQL #

UPDATE security_user usr
    SET password = '{noop}password123',
        failed_login_attempts = 0,
        activated = true
    FROM security_role rol
    JOIN security_organization org ON org.uuid = rol.organization_uuid
    WHERE rol.uuid = usr.uuid
    AND usr.name = 'admin'
    AND org.is_system = true;

password123 is replaced with the new password, the prefix {noop} remains in place.

MariaDB #

UPDATE security_user usr
    JOIN security_role rol ON rol.uuid = usr.uuid
    JOIN security_organization org ON org.uuid = rol.organization_uuid
    SET usr.password = '{noop}password123',
        usr.failed_login_attempts = 0,
        usr.activated = true
    WHERE usr.name = 'admin'
    AND org.is_system = true;

password123 is replaced with the new password, the prefix {noop} remains in place.

Creating an additional system administrator #

Without access to the database, an additional system administrator can be created at server startup. For this, the environment variables OTHERSYSTEMADMIN_USERNAME and OTHERSYSTEMADMIN_PASSWORD are set, or alternatively the keys username and password under relution.system.otheradmin in the application.yml. After a restart, Relution creates the user in the system organization and adds it to the administrator group.

relution:
  system:
    otheradmin:
      username: ""
      password: ""

If a user with this name already exists in the system organization, it only regains administrator rights, its password remains unchanged. After logging in, the entries should be removed again so that the password does not remain in the configuration permanently.

Server does not start #

The log files, which by default are located in the log directory inside the Relution installation directory, should be checked.
If the problem cannot be identified independently, a support ticket should be opened and the logs provided.

Log files #

Where to find log files for Docker, Linux, and Windows is described under Relution Logs →.

Performance analysis with Glowroot #

In case of performance problems, Relution support may ask for an analysis using Glowroot →. Glowroot records which requests take how long and shows the result in a web interface of its own.

When running in Docker, Glowroot is not part of the image, it is downloaded automatically on startup as soon as RELUTION_ENABLE_GLOWROOT is set:

  relution:
    image: relution/relution:latest
    environment:
      - RELUTION_ENABLE_GLOWROOT=true
      - RELUTION_GLOWROOT_ADMIN_JSON_BASE64=ewogICJ3ZWIiOiB7CiAgICAiYmluZEFkZHJlc3MiOiAiMC4wLjAuMCIKICB9Cn0=
    ports:
      - '4000:4000'

The second variable merely contains the base64 encoded Glowroot configuration {"web": {"bindAddress": "0.0.0.0"}}. Without it, the interface can only be reached from inside the container. After restarting the container it is available on port 4000.

The recordings are kept inside the container and are lost as soon as it is recreated. For the duration of an analysis this is usually sufficient. To keep them, set RELUTION_GLOWROOT_DIR to a directory writable for UID 20001.

To disable it, remove RELUTION_ENABLE_GLOWROOT again and restart the container.

Security notes #

• Install the latest operating system and software updates and security patches
• Use strong passwords for administrator accounts
• Use long passwords for service-to-service communications, these passwords do not need to be used or remembered by humans
• Make sure the user account used to access LDAP has Read-only access
• Do not create accounts with weak passwords such as password or test
• Do not store passwords in files that are globally readable