Admin Overview

The administration tab is divided into multiple sections covering a variety of administrative actions, as detailed below.

Account Information

This section is to view installation metadata to help customers work with Heimdall Support in enrolling for complimentary support. Account ID is an GUID of the installation, while Registered ID is provided from Customer Support to verify enrollment. Enrollment can be confirmed by a checkmark next to the field (as well as the removal of the UNSUPPORTED banner) see below:

License Configuration

In this section, a new license file can be uploaded when provided by Heimdall, and the current settings and license use can be observed. In Demo mode, up to 4 LB servers can be used, and up to four VDBs with rules (optimizations) can be enabled for 30 days. The used count is only based on VDBs that have received traffic in the last 30 seconds, so will dynamically account for activity. If the used values surpass the allowed values, then a warning will be displayed on the console, but no restriction in features will be enforced. License handling is strictly advisory, i.e. while the system may complain about a license being invalid, it will not restrict what is done, to insure no outages occur as a result of licensing.

Note: When using an AWS paid-for instance, the proxy use on the instance will not count toward license use. Additionally, added paid-for instances can be reconfigured to be a pure proxy instance and will also not count to license use on another management server.

Log Management

Log Files Management

This section is provided to assist in managing log files and configuring data source used for logging. Core dumps are files that are generated by the operating system when a program terminates abnormally, such as by crashing or encountering an error. Heap dumps are files that contain a snapshot of the Java Virtual Machine (JVM) heap at a specific point in time. This functionality is removing all core files from /var/lib/systemd/coredump folder and also core files and heap dumps files from the project directory.

Log Database Management

By default, an embedded database supplied with Heimdall is used to store logs and statistics, however there is an option to select user configured data source (MySQL, PostgreSQL, Oracle and SQL Server supported). If Heimdall is unable to establish connection to selected source at any point it will fall back to using embedded one. User configured in selected data source has to have database root privileges.

S3 Log Bucket Configuration

In this section, we can configure log uploads to S3. There is an option to specify the S3 bucket where the logs should be saved.

Security Tags

This section allows for the management of security tags, which can be applicable in the database browser section of Source tab. Each resource (i.e. databases, schemas, tables, views, columns) in the database browser can be tagged with one or more tags. The admin can select a specific tag from the dropdown and filter out the tagged resources.

Warnings:

1. If you delete a resource in your database that had assigned security tags and later decide to recreate it, it will inherit those tags.
2. If you change the name of a given resource in your database, the security tags assigned to it will be lost.

Software Management

This section allows for management of the software. In the first dropdown, you can select a version of code to update to. Release is the normal release train of code, test versions are generally just before a new release, and development are the often daily updates that have completed regression testing. Customers will often be asked to update to the development build if they have encountered a problem and want to apply the fix for it. To apply a particular version, select the version in the dropdown, then click "Update via Repository". Please note, if you have independent proxies running (vla NLB or as a service), you will need to restart them independently as well. To check the version of code each proxy is running, please refer to the status tab.

Note: Any build pushed as a development build have passed all regression testing that any previous version has passed. What may not yet be complete are regression tests for the new changes, which often are developed in parallel with customer testing of the changes. This can result in frequent development builds, but allows for rapid test/fix/deploy cycles during customer POC processes. Once a POC is completed, we will work with customers to schedule a full release build for use in production that has completed full and updated regression testing.

You can also update the version of Heimdall by providing the url link to the zip file, complete this action using Update via URL button.

In the event that you want to update to a particular version of Heimdall that was provided to you as a zip file, you can use the third section for a manual update. Simply select the heimdall zip file, then update via File.

The next option is the Shutdown/Restart Heimdall button, which will not explicitly trigger a restart, but will rely on any restart mechanisms on the server to trigger the actual execution of the server after it terminates.

In the event you need to download the Heimdall driver (say to use as a jdbc driver) the next option "Download Heimdall Driver" can be used.

If you need to roll back to a previous version of the system, the quickest way is to use the "Rollback Version" button. Heimdall stores two versions of the system - the current and the previous - and you can swiftly switch between them.

Following is the release notes link, for the most current release notes.

Note, for command line manual update, please do the following:

1) copy the file into the install directory as heimdall-new.zip 2) cd to install directory 3) execute the following commands:

* sed -i "s/\s*\"modules\/.*\",*//g" config/heimdall.conf
* unzip -j heimdall-new.zip

4) kill and restart the heimdallserver.jar process: ps auxw | grep heimdallserver.jar root 4198 0.0 0.0 6100 624 pts/0 S+ 18:03 0:00 grep --color=auto heimdallserver.jar root 26005 30.8 4.0 9679444 638504 ? Sl 17:58 1:25 java -server -XX:+ExitOnOutOfMemoryError -jar /opt/heimdall/heimdallserver.jar

kill 26005

The next option is the Migration button, which initiates the download and execution of the 'heimdall-migration.sh' script. The script carries out all necessary actions to meet the requirements for the upcoming release.

Current migration steps:

1. Install Java 17 and set it default

2. Update heimdall-entrypoint.sh script

If there will be an issue with download file, you will receive an error with link to the script:

If you encounter this issue, proceed to download the migration script manually here. Before executing the script, ensure it has the necessary execute permissions:

chmod +x heimdall-migration.sh

To manually run the migration script on the Heimdall Manager host, use the following command:

bash heimdall-migration.sh

If an error occurs during migration with retrieving the latest file heimdall-entrypoint.sh, it should be downloaded from here, placed on the host where migration is being conducted, and the path to it should be provided as an argument to the script:

For example: bash heimdall-migration.sh /tmp/heimdall-entrypoint.sh

Alerts

This section provides a list of any alerts that have been dismissed with the check. Any alerts in this list will not be shown in the top of the GUI until cleared.

Sending alerts via notification: If this option is checked, every alert which message doesn't match any added pattern, will be sent via notification. If no pattern is added, all alerts will be sent via notification.

Notifications

This section provides the capability to create group notifications. Users can choose from three supported protocols: AWS SNS, LDAP, or SMTP. Additionally, there is an option to view the list of emails associated with a particular entry by clicking the envelope icon. This will display a popup showing the email addresses.

System notification: This option allows to choose which notification config is used as system notification and will be used to send various system messages, such as alerts by default.

When choosing AWS SNS for email (and potential SMS) notifications, it will require Heimdall to be hosted on the AWS platform, having appropriate AWS IAM roles and permissions configured to interact with AWS SNS.

When choosing SMTP, user will be able to define his mailing list (from existing Heimdall defined users in Users tab). Also, please remember to configure SMTP client in the Admin tab -> Smtp Configuration.

Additionally, it's possible to create a "none" type notification, meaning without specifying any group or recipients. This is used in portal mode, where it can be assigned to a Role Config that should be auto-approved. Such empty notifications without recipients can only be created with the SMTP protocol.

After making any changes, they must be submitted using the Commit button.

Portal

This section is generally used to configure settings related to the portal. Within it, we can define the LDAP configuration, from which portal users will be sourced, the data source where portal data will be stored, and several checkboxes.

• Portal data source - Data source where portal data will be stored.
• Show approvers emails - If selected, it will be possible for all users to view approvers' emails for a specific role. Admins can always see these emails, even without the checkbox being checked.
• Synchronize Portal Users - Indicates that if the LDAP Group Filter matches, Heimdall (GUI) users will be created automatically.
• Require specific justification format - If selected, there is an option to specify the regex that the justification must match when requesting a session.
  • Regex pattern - Specifies the regex that must be matched in the justification field.
  • Invalid justification message - Specifies the message to appear when requesting a session if the justification content does not match the configured regex.

SMTP Configuration

This section provides the functionality to establish SMTP configurations for email dispatch. Users can adjust the configuration to their preferences, by incorporating relevant properties in the SMTP Properties section (available properties can be found here: https://javaee.github.io/javamail/docs/api/com/sun/mail/smtp/package-summary.html ). The Heimdall team recommends users set the ssl protocol to TLSv1.2 or TLSv1.3, otherwise TLSv1 might be used. The Email Tester component, allows users to validate configuration before committing changes by sending a test email. If changes will are not committed, all entered configuration will be lost. While using e.g. Google smtp, user should consider using application password rather than their personal password - especially if the account has 2fa enabled, then without app password functionality might have problem to operate.

Login History

This provides the login times, account ID and source IP of the recently recorded GUI logins.

Unchecking 'Exclude proxy logins' will result with adding proxy logins to the list.

Cache Drivers

This section allows a cache driver (specifically Hazelcast) to be uploaded for use by Heimdall instead of the built-in driver. This allows the driver to match what may exist in a customer's environment if our version causes a conflict.

Server Properties

These are properties that can control overall Management server behavior, and will be added to over time. Current properties supported.

• Disable Cert Validation: Disable TLS certificate validation for software downloads (Boolean)
• Enable Portal Mode: Value that indicates if after successful login central manager or portal mode will be used (Boolean)
• Minimum free disk space %: configured how much space needs to be free for any configuration saves to occur. Defaults to 1 for 1%. This helps prevent configuration loss if not enough space is available to successfully save the full configuration. (Double)
• Log Events To Console: For debugging or container use, log ALL events to the stdout console of management server (Boolean)
• Max Log Age: Sets the maximum age in days of log files and log records (Integer)
• Enables password validation: Validate new users password along with provided rules (Boolean)
• Proxy Host: If a proxy is needed to access the Internet for code update notifications and downloads, the host to use for this (String)
• Proxy Password: Proxy password for proxy authentication, no default (String)
• Proxy Port: The port defaults is 3128 (Integer)
• Proxy User: Proxy user for proxy authentication, no default (String)
• Redirect Config Fetches: Value that indicates if server should redirect all HTTP config requests to HTTPS Tomcat port (Boolean)
• Reserved Disk Space: Sets the amount of FREE memory to maintain on the log filesystem (Double)
• Verbose Debug Mode: On the server, enable verbose debug mode (Boolean)
• Session Timeout: Controls HttpSession idle-timeout expiration (default value is 30 minutes) for GUI users
• Log Rotation Interval: A period between log rotation (in minutes)
• Enable Manager CloudWatch Logging: Value that indicates if manager logs should be sent to AWS CloudWatch. May incur additional AWS charges (Boolean)

Modules

Allows modules to be added or removed as needed. The fewer the modules, the faster a Heimdall node can startup. In particular cache modules that are unused should be deleted as some can add significant load time.

Password Policies

This section allows user to set up requirements that specific user password must meet to be created/updated. Current rules supported:

• minimum/maximum of characters - minimum/maximum number of characters that password must contain (with minimum/maximum parameter tht defines the limit).
• digits requirement - rule defining that password must contain at least one digit
• special marks requirement - rule defining that password must contain at least one special mark
• uppercase character requirement - rule defining that password must contain at least one uppercase character
• custom regex matching - rule that provides a pattern parameter with the regular expression to which password must match

The Password Policies apply to GUI Heimdall users but do not extend to users with external passwords, such as those using LDAP, Kerberos, or AWS Secrets.

Config Management

This section allows editing startup /etc/heimdall.conf configuration file, which can be used to populate environmental variables or cloud environments. The user can set options described below.

Option Name	Description	Default value
hdRole	proxy
hdHost	Hostname of management server	heimdallmanager
hdPort	Port of the management server, generally 8087 or 8443	8087
secure	If the proxy should use HTTPS to connect to the manager	false
hdUser	Login username for the management server, can be admin	admin
hdPassword	Login password for the management server	heimdall
javaOptions	Any arbitrary options desired to be set	-server -XX:+ExitOnOutOfMemoryError -XX:+IgnoreUnrecognizedVMOptions -XX:-MaxFDLimit -XX:+UnlockExperimentalVMOptions
hdSecretKey	In AWS, use this as the name of an "AWS Secret" to store the configuration, protecting included passwords from being written to disk. To use, proper permissions must be set on the IAM role. This option provides two major benefits. First is that all passwords are stored in AWS Secrets, in an encrypted format. Second is that redeployment of a management server can be done with a configuration pre-populated, so there is no need to backup and restore configurations to account for failures. Simply terminate the old instance and a new instance with the same user-data will be created with the same configuration as the original.
vdbCredentialsSecretName	A virtual database access and secret keys will be fetch from AWS secret manager using this value. It works only when the cloud option is set to AWS. Use this variable instead of hduser and hdpassword when VDB is configured with Access/Secret Keys using Secrets Manager.” An optional way to set this value is to enter an "hdUser" field starting with "secret:" and the name of the secret. This will only override the secret name if it is otherwise blank.

Kerberos Configuration

This tab allows configuring Kerberos to authenticate users in the Heimdall Manager.

Option Name	Default Value	Description
Enable Kerberos Authentication	---	Enable Kerberos Authentication for Heimdall Manager
Service Principal	HTTP/localhost	Identity for a service instance in Kerberos
Keytab Location	/etc/krb5.keytab	File path to the file that stores pairs of Kerberos principals and their corresponding encrypted keys
Enable LDAP Groups Extraction	---	Perform LDAP groups extraction on successful authentication
LDAP Configuration	---	LDAP Configuration used for groups extraction

LDAP Configuration (Proxy & Central Manager)

LDAP Authentication provides authentication with using of LDAP server. LDAP Authentication provides two modes of authentication:

• Bind + Search Mode - authentication is made by binding to server as admin and searching information about authenticated user;
• Simple Mode - authentication is made by binding to server as authenticated user.

Bind + Search Mode

To configure Bind + Search Mode, below options can be set.

LDAP option	Required?	Description	Example value
LDAP(S) URL	yes	Specifies URL of LDAP server. Instead of just one URL, you can also supply a space-separated list of URLs. In this case, the LDAP provider will attempt to use each URL in turn until it is able to create a successful connection.	ldap://server.example.com:389
Server Type	yes	Specifies the type of LDAP Server	RedHat IDM (FreeIPA)
LDAP Security Principal	yes	Specifies name of user used to search for authenticated user	CN=ro-admin,CN=Users,DC=example,DC=com
LDAP Sec. Security Principal	no	Specifies name of user used to search for authenticated user in case the primary search with LDAP Security Principal fails.	CN=admin2,CN=Users,DC=example,DC=com
LDAP Search User Password	yes	Specifies password for LDAP Security Principal user used to search for authenticated user	examplepassword123
LDAP Sec. Search User Password	no	Specifies password for LDAP Sec. Security Principal.	examplepassword321
LDAP Search Domain	yes	Specifies LDAP search domain, the domain in which authenticated user's groups will be searched.	DC=example,DC=com
LDAP User Search Base	yes	Specified LDAP user search base in which authenticated user will be searched.	CN=Users,DC=example,DC=com
LDAP Name Attribute	yes	Specifies name attribute by which authenticated user	sAMAccountName
LDAP Group Name Attribute	no	Optional, specifies group's name attribute which should be read during extracting authenticated user's groups. If not provided, LDAP Name Attribute will be used instead.	CN
LDAP Group Filter	no	Optional, option used during searching for authenticated user. Setting this option limits the number of groups to search user into them, only to particular group inside server. Setting this option makes it required to extract at least one group to authenticate the user.	(DistinguishedName=CN=group1,CN=Users,DC=example,DC=com)
Use nested groups filter	-	Specifies if parent groups should be included, when searching for user's groups.	-
Ignore LDAP Cert	-	Specifies if TLS validation of LDAP server certificate should be performed	-
LDAP Healthcheck	no	Performs LDAP Healthcheck automatically every minute. An appropriate alert will be shown if the server goes down (Similarly, once the server is back online).	-
Management privileges	no	Determines whether it entitles a user to use admin/read only privileges by requiring membership in a specific group.	-
Admin privilege group	no	To be authorized to use the Management Privilege: Admin, the user must be a member of the selected group.	-
Read Only privilege group	no	To be authorized to use the Management Privilege: Read Only, the user must be a member of the selected group.	-

By choosing option Simple LDAP Mode, you can switch to Simple Mode.

Advanced group filter

LDAP group filter is used to limit number of groups for look up for authenticated user. Example value describes filter limiting number of groups to only one particular group, but this option value is added as written, what enables writing more complex filters. Please look on below example.

Let's assume that we want our user be from groups group1 or group2. By knowing the syntax of search filter used in LDAP server we can set LDAP Group Filter as:

(|(DistinguishedName=CN=group1,CN=Users,DC=example,DC=com)(DistinguishedName=CN=group2,CN=Users,DC=example,DC=com))

Important: If there is an LDAP Group Filter specified at least one group has to be extracted to authenticate the user.

LDAP Healthcheck

If enabled, performs in the background automatically every minute and may result in two alerts: once the server is down, and once the server is back online.

Nevertheless, it can be performed on demand by using the button with hearth - if used, the JSON with the details of LDAP Healthcheck result will be opened in the new tab.

Important: LDAP Healthcheck on demand will be performed on ALL configurations with LDAP Healthcheck checkbox enabled.

AWS Secrets Manager for LDAP Security Principal

On AWS environments there is additional option available represented as a checkbox located beside both Security Principal inputs. When enabled, instead of Search Password, Secret Name can be typed. After commiting the changes the credentials for Security Principal will be automatically fetched from the AWS and cached on both manager and proxy instances. This configuration supports rotating passwords, which means that in case of connection failure (due to credential rotation most likely) the system will silently pull the newest values and try to establish the connection again.

For those utilizing a custom secrets manager, it is imperative to adhere to the structure outlined in AWS RDS secrets manager. For instance, the JSON format should resemble the following: {"username":"test","password":"test"}.

Simple Mode

Simple Mode is simpler mode than Bind + Search mode, because uses only one request (which is binding request) to LDAP server.
Simple Mode can be turned on by choosing Active Directory (LDAP) Auth Enabled checkbox, and then choosing Simple LDAP Mode checkbox. Simple Mode requires to set below options to work properly.

LDAP option	Required?	Description	Example value
LDAP(S) URL	yes	Specifies URL of LDAP server. Instead of just one URL, you can also supply a space-separated list of URLs. In this case, the LDAP provider will attempt to use each URL in turn until it is able to create a successful connection.	ldap://server.example.com:389
LDAP Prefix	yes	Specifies prefix used in during bind authenticated user to LDAP server	CN=
LDAP Suffix	yes	Specifies suffix used in during bind authenticated user to LDAP server	,CN=Users, DC=example, DC=com

To understand working of this mode, should be known that send request is binding composed of three parts: prefix + username + suffix. For given example values and user exampleuser, binding request would look like CN=exampleuser,CN=Users, DC=example, DC=com.

Central Manager Information

If you want to authenticate CM user, in the Users tab you should create new user(-s) with the same name as in your active directory. During creating new user don't forget to mark the "Authenticate By LDAP" option.

LDAP Configuration Wizard

The LDAP Configuration Wizard is provided to simplify configuration process as much as possible. It's a walk-through tool preventing from going forward if provided configuration is not valid. It can be accessed by clicking the "LDAP Wizard" button in the LDAP Configuration section.

Bind + Search Mode

There is the list of information necessary to finalize the Wizard Configuration:

• LDAP(S) URL - Specifies URL of LDAP server.
• Ignore LDAP Cert - Specifies if TLS validation of LDAP server certificate should be performed.
• LDAP Security Principal - Specifies name of user used to search for authenticated user.
• LDAP Sec. Security Principal - Specifies name of user used to search for authenticated user if the primary search fails.
• LDAP Search User Password - Specifies password for LDAP Security Principal user used to search for authenticated user.
• LDAP Sec. Search User Password - Specifies password for LDAP Sec. Security Principal user used to search for authenticated user.
• LDAP Security Principal Secret Name - Specifies the name of an AWS Secret containing the credentials (user/username and password) of the LDAP Security Principal. Available only if 'Secret' is enabled.
• LDAP Sec. Security Principal Secret Name - Specifies the name of an AWS Secret containing the credentials (user/username and password) of the LDAP Sec. Security Principal. Available only if 'Secret' is enabled.
• LDAP Search Domain - Specifies the domain in which authenticated user's groups will be searched.
• LDAP User Search Base - Specifies user search base in which authenticated user will be searched.
• LDAP Name Attribute - Specifies attribute which should be used to identify a user.
• LDAP Group Name Attribute - Specifies attribute, which should be used to extract information about a group (Optional).
• LDAP Group Filter - Specifies group filter, which will be added during a search for a user's groups (Optional).
• Use nested groups filter - Specifies if parent groups should be included, when searching for user's groups.
• LDAP Healthcheck - Performs LDAP Healthcheck automatically every minute. An appropriate alert will be shown if the server goes down (Similarly, once the server is back online).
• Cache groups' emails - Specifies whether emails for LDAP groups should be cached (applies only if LDAP configuration is linked to the portal configuration).
• Cache time - Specifies the interval at which emails in the cache should be updated.
• Management privileges - Determines whether it entitles a user to use admin/read only privileges by requiring membership in a specific group.
• Admin privilege group - To be authorized to use the Management Privilege: Admin, the user must be a member of the selected group.
• Read Only privilege group - To be authorized to use the Management Privilege: Read Only, the user must be a member of the selected group.

Service Account Validation

At the very beginning, the absolute basis of the correct and valid configuration:

• The fields above are required as the authentication is made by binding to server as admin and searching information about authenticated user.
• The grayed-out "Verify" button will remain gray until all required fields are filled in.
• When all the required fields are filled in, the button will turn green and when pressed, the connection to AD will be attempted.
• If it fails, a corresponding message with the reason for the error will be displayed.
• if it succeed, the next Wizard stage will be unlocked.

If cloudOption: aws is selected in Config Management, then AWS Secrets can be used to provide credentials for LDAP (Sec.) Security Principal.

In such case it is obligatory to provide either '${username}' or '${user}' placeholder where the actual username (retrieved from AWS Secrets Manager, based on LDAP (Sec.) Security Principal Secret Name) has to be injected in the distinguished name (DN).

Wrong way: Good way:

Users & Groups Search Details

The next step is necessary to properly look for information about the user being authenticated and the groups he belongs to + set whether nested groups should be searched for.

• In order to simplify configuration some of the fields can be filled using dropdowns (LDAP Search Domain and LDAP Search Base contains all possible options straight from LDAP Server).
• LDAP (Group) Name Attribute contains all attributes which are actually used among all configured users / groups with additional counter of how many users / groups actually contain particular attribute.
• Additional "Example users found" row will be shown after LDAP Name Attribute selection. This row is just a preview and has no affect on the final configuration, but what is important - these values will be treated as logins for users to authenticate.
• Caching emails for LDAP groups is enabled by default, with a cache update time of 1 hour. This can be customized to fit your needs or disabled altogether. However, the minimum update time must be at least 5 minutes.
• All of these fields can be customized after checking suitable checkbox on the right.
• When all the fields are filled in, the button will turn green and when pressed, the attempt to find Groups configured on the server will be performed.

LDAP Group Filter Creation

The almost last step of the Wizard is to select Groups of interest for the DB i.e. Groups which will be relevant to database roles. Based on the selected Group the LDAP Group Filter will be generated when you click "Generate Filter" button. If no group is selected then no filter will be provided and this is ok - LDAP Group Filter is optional.

Management Privileges

As an option, Management Privileges can be enabled to enhance security. When activated, only members of the specified groups will have access to the assigned in the Users tab Admin or Read-Only privileges.

Authentication Checker

Provided configuration can be verified with the last part of the LDAP Configuration Wizard - Authentication Checker. In case of successful authentication extracted groups will be listed, as long as LDAP Group Filter is specified.

Simple Mode

In Simple Mode, unlike Bind + Search Mode, only the url suffice to start the configuration. Nevertheless what is important, the LDAP Configuration Wizard does not work with Active Directory, as this one has a strong security authentication and requires a successful bind before any data can be retrieved. Regardless of the success of the scan the next part of the Wizard wll be unlocked.

After successful scan all possible LDAP Prefixes and LDAP Suffixes will be available in a drop-down list. After failed scan drop-down lists will be empty, nevertheless both these fields can be customized after checking suitable checkbox on the right.

At this point your Simple LDAP Configuration is complete and after saving it can be found under "LDAP Configuration".

TCP

This allows checking if given port is available. Host is optional, if it isn't provided, it is set to "localhost".