Appendix

Troubleshooting

Lost password

If you’ve lost access to BlueRange’s system administrator account and you’re unable to reset your password using the configured email address, it is also possible to reset the password through the database. This procedure requires write access to the database server and BlueRange’s database on the database server.

Please try to reset your password using the "Forgot your password?" link before attempting the steps below. You should treat these steps as an option of last resort.

To reset the password, you’ll first have to connect to the database using the command line or a management tool. Then execute the SQL script that is appropriate for your database server.

MariaDB/MySQL

UPDATE security_user usr
    JOIN security_organization org on org.uuid = usr.organization_uuid
    SET password = SHA1(CONCAT('password123', '{', usr.uuid, '}'))
    WHERE usr.name = 'admin'
    AND org.name = 'system';

Replace password123 with the new password you want to use.

Microsoft SQL Server

UPDATE security_user SET password = LOWER(CONVERT(VARCHAR(40), HASHBYTES('SHA1', CONCAT('password123', '{', usr.uuid, '}')), 2))
    FROM security_organization org
    JOIN security_user usr on usr.organization_uuid = org.uuid
    WHERE usr.name = 'admin'
    AND org.name = 'system';

Replace password123 with the new password you want to use.

Oracle Database

On Oracle you can use DBMS_CRYPTO to generate the hash code, but this method requires the Enterprise Edition and you may have to specifically grant access for your user (GRANT EXECUTE ON SYS.DBMS_CRYPTO TO <user>).

To work around this, you can use a command line utility like shasum, sha1sum, FCIV or any other tool that can produce SHA1 hash codes to generate the hash. For security reasons we strongly recommend that you do not use online utilities/websites to produce the hash code.

Examples:

echo -n "password123{<uuid>}" | sha1sum

# Sample input and output
echo -n "password123{FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF}" | sha1sum
# Output: 21b2dec34062876518eb2a221e8bd920b2c75e80

Replace password123 with the password you want to use. Replace <uuid> with the user account’s UUID. Make sure to include the curly braces in your input.

You can test with the sample input above. If everything is working as expected, your tool should produce the same output as shown here. Note that you cannot use the hash code from this example for your user account, because the value from which the hash code is generated must include the user’s actual UUID (salted hash code).

UPDATE (
	SELECT
		usr."uuid",
		usr."name",
		usr."password"
		FROM "security_user" usr
		JOIN "security_organization" org ON org."uuid" = usr."organization_uuid"
		WHERE org."name" = 'system'
		AND usr."name" = 'testadmin'
)
SET "password" = '<output-of-shasum>'

Replace <output-of-shasum> with the salted SHA1 hash code you have generated (the hash code from the example above will not work for your account).

Server won’t start

Please examine the log files found in the log directory located beneath BlueRange’s installation directory. If you are unable to identify the issue on your own, please open a support ticket and provide the logs to us.

Log files

BlueRange’s log files can be found in the "log" directory located underneath its installation directory. Logs are rotated automatically once a day and old log files are compressed to save space.

Docker

Because Docker containers are expected to be ephemeral, BlueRange does not write log files when run inside a container. To get logs from a running container use the docker logs command.

We recommend to set up a logging infrastructure to ensure logs are properly collected and archived to help with troubleshooting in case of issues.

See: https://success.docker.com/article/logging-best-practices

Linux

If BlueRange was installed in the default directory "/opt/bluerange" logs can be found in "/opt/bluerange/log". The most recent log file is called bluerange.log, while archived log files are named bluerange.log.<date>.gz. If BlueRange was installed in a different location, the log directory is found relative to its installation directory.

Windows

If BlueRange was installed in the default directory "C:\Program Files{productSmall}" logs can be found in "C:\Program Files{productSmall}\log". The most recent log file is called bluerange.log, while archived log files are named bluerange.log.<date>.gz. If BlueRange was installed in a different location, the log directory is found relative to its installation directory.

Security considerations

  • Do install the latest OS and software updates and security patches

  • Do use strong passwords for administrator accounts

  • Do use long passwords for service-to-service communication, these passwords don’t need to be used or remembered by humans

  • Do make sure the enterprise account used to access your LDAP has read-only access

  • Don’t create accounts with weak passwords like “password” or “test”

  • Don’t store passwords in files that are world readable.