Heimdall.conf


The file is a configuration file and can be used to populate environmental variables or cloud environments. It should be generated at directory: /etc/heimdall.conf

It can contain different options which should be echoed out if necessary with syntax: "${optionName}=${optionValue}":

Main Option Name Description
hdRole It can be used to control if this environment is a central manager or a proxy
hdHost Hostname of management server
hdPort Port of the management server, generally 8087 or 8443
hdUser Login username for the management server, can be admin
hdPassword Login password for the management server
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.
cloudDetection If the manager should detect cloud services on startup
cloudOptions (Available when cloud Detection is disabled) For heimdall running on premise to allow using cloud services, initializes on startup
(none, aws, azure, gcp, oracle)
javaOptions Any arbitrary options desired to be set
vdbName Exact name of the vdb to service
secure If the proxy should use HTTPS to connect to the manager

Example user data script:

#!/bin/bash
(
echo "cloudDetection=true"
echo "cloudDetection=aws"
echo "hdHost=HostNameOfManagementServer"
echo "hdPort=8087"
echo "hdRole=server"
echo "hdPassword=secretSafeLongPassword"
echo "hdUser=admin"
echo "secure=false"
echo "vdbName=SQL_DB"
) > /etc/heimdall.conf

The Proxy can authenticate to the Central Manager via secrets. Below environmental variables can be set instead of hdUser and hdPassword when VDB is configured with Access/Secret Keys. 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. Most of those variables will be automatically set via using secrets checkbox in the Config Management section of Admin tab.

Secrets Option Name Description
useSecretForVdbCredentials If the VDB will use secret for Access/Secret keys. Available options: true, false.
vdbCredentialsSecretName A VDB access and secret keys will be fetched from the Secrets Manager using this value.
secretsManagerConfigName Name of the Secrets Manager Config. If you are setting it manually, it can be random name.
secretsManagerType Type of the Secrets Manager Config. Available options: AWS, CYBERARK_CONJUR, HASHICORP_VAULT.

The specific environmental variables for HashiCorp Vault Secrets Manager.

HashiCorp Vault Option Name Description
VAULT_ADDR The URL of the Hashicorp Vault instance.
VAULT_TOKEN Token used for authentication. It should have permissions appropriate to access deserved secret values.

The specific environmental variables for CyberArk Conjur Secrets Manager.

CyberArk Conjur Option Name Description
CONJUR_APPLIANCE_URL The URL of the Conjur instance you are connecting to. When connecting to Conjur Enterprise configured for high availability, this should be the URL of the master load balancer (if performing read and write operations) or the URL of a follower load balancer (if performing read-only operations).
CONJUR_ACCOUNT Conjur account that you are connecting to. This value is set during Conjur deployment.
CONJUR_AUTHN_LOGIN User/host identity.
CONJUR_AUTHN_API_KEY User/host API key (or password).
CONJUR_AUTHN_URL (optional) Alternate authentication endpoint. By default, the client uses the standard <applianceUrl>/authn for generic username and API key login flow.

For example, if you want to use CyberArk Conjur as a Secrets Manager manually.

#!/bin/bash
(
...
the above main options without hdUser & hdPassword...
...
echo "useSecretForVdbCredentials=true"
echo "vdbCredentialsSecretName=Test/secret"
echo "secretsManagerConfigName=random_name"
echo "secretsManagerType=CYBERARK_CONJUR"
echo "CONJUR_APPLIANCE_URL=<your-appliance-url>"
echo "CONJUR_ACCOUNT=<your-account>"
echo "CONJUR_AUTHN_LOGIN=<your-authn-login>"
echo "CONJUR_AUTHN_API_KEY=<your-api-key>"
) > /etc/heimdall.conf
Once initialized, this configuration can be adjusted manually if necessary. Note, if the hdRole is set, then the instance will automatically allocate 80% of instance memory for the process (server or proxy). This can be tuned in the /etc/heimdall.conf as needed as well. These settings will effectively allow auto-scaling groups of proxies to be configured.


Please note: If building an AMI for auto-scaling, which may be used by multiple scaling groups with different configurations, it is suggested that after doing initial testing, the heimdall.conf be deleted so that user-data will be re-read to build the Heimdall configuration. This will leverage the user-data on each new initialization to build the configuration at startup.