Configuring Instana backend on Docker

The settings.hcl file is generated during the installation process. This file has all the configurations, such as download key, sales key, Instana related configurations like profile, tenant name, unit name, and hostname of the environment. These configurations are needed to install the Instana backend. You can configure this file, and then Instana-console uses this file to install Self-Hosted Classic Edition (Docker).

If required, create a settings.hcl file with default (empty) values by running the following command:

instana settings template

The values for the following parameters are populated during the installation:

type      = "single"
profile   = "normal"
tenant    = "<Your-tenancy-identifier>"
unit      = "<Your-backend-identifier>"
agent_key = "<Your-agent-key>"
sales_key = "<Your-sales-key>"
host_name = "<The-FQDN-of-the-machine-the-backend-is-installed-on>"
token_secret = "<max_12_digits>"

cert {
  crt     = "<Path-to-your-signed-certificate>"
  key     = "<Path-to-your-private-key-file>"
}

If you want to change the parameters, run the vi settings.hcl command. To apply the new configuration settings to your Classic Edition, run instana update command.

Instana defaults to the following directory structures:

dir {
  metrics  = "/mnt/metrics"
  traces   = "/mnt/traces"
  data     = "/mnt/data"
  logs     = "/var/log/instana"
}

All data stores require authentication. Optional: Configure the credentials. Credentials that are not specified are initially generated and added to the settings.hcl file. You can change the passwords by updating them in the settings.hcl file.

To apply the changes, run the following command:

instana update

...
datastore "cassandra" {
  user     = "cassandra"
  password = "SECURE_PASS"
}
datastore "elasticsearch" {
  user     = "elastic"
  password = "SECURE_PASS"
}
datastore "kafka" {
  user     = "kafka"
  password = "SECURE_PASS"
}
datastore "clickhouse" {
  user     = "clickhouse"
  password = "SECURE_PASS"
}
datastore "postgres" {
  user     = "postgres"
  password = "SECURE_PASS"
}
datastore "aggregator" {
  user     = "aggregator"
  password = "SECURE_PASS"
}
...

To enable HTTP Strict Transport Security (HSTS) globally, add the following flag in the root of the settings.hcl file:

hsts_enabled = true

The URL to the local open API specification is https://{onpremhost}/docs/openapi (after on-premises release 170). For more information about how to configure REST API clients, see Web REST API docs.

To replace existing certificates with other certificates, update paths to your certificate files in the settings.hcl file by using the following command:

cert {
...
}

Then, update the system by running the following command:

instana update -f /path/to/settings.hcl

cert {
  crt = "/mnt/cert/tls.crt"
  key = "/mnt/cert/tls.key"
}

If Instana can't validate the certificate that your SMTP server presents, you might see the following TLS error:

ERROR c.i.email.service.client.JavaMail - Mail could not be send due to an error
javax.mail.MessagingException: Could not convert socket to TLS

To configure your Instana installation to successfully send data to a webhook with a custom certificate, provide a custom Java™ keystore (jssecacerts) that contains your certificate for JVMs.

Complete the following steps to configure your Instana installation:

1. Copy the current JVM keystore from your JVM $JAVA_HOME/lib/security/cacerts.

2. Import your custom certificate into this keystore by using the JVM keytool with the following command:

   $JAVA_HOME/bin/keytool -importcert -file custom-crt.crt -alias instana.com -keystore cacerts -storepass changeit
   

3. Add the absolute path of the keystore by setting the custom_keystore configuration key in the root of the settings.hcl file.

   custom_keystore="<path_to_javakeystore>"