Configuring Instana backend on Docker

Creating a template for the settings.hcl file

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 you want to install Instana, you need to install the settings.hcl file.

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

instana settings template

Default configurations

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.

Data directories

Instana defaults to the following directory structures:

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

Data store credentials

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

Only passwords can be changed. Users are fixed and cannot be changed.

...
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"
}
...

Data retention

retention {
  metric_roll_up_5     = 86400
  metric_roll_up_60    = 2678400
  metric_roll_up_300   = 8035200
  metric_roll_up_3600  = 34214400
}

env_var "FLAGS_retention_10s"{
  value="86400"
}
env_var "FLAGS_retention_60s"{
  value="2678400"
}
env_var "FLAGS_retention_300s"{
  value="8035200"
}
env_var "FLAGS_retention_3600s"{
  value="34214400"
}

retention {
  app_data_short_term  = 7
}

Settings

docker_repository {
  base_url = "my.mirror.internal/v2/artifact-public.instana.io"
  username = "user"
  password = "pass"
}

eum {
  tracking_base_url     = "https://mobile.acmecorp.com/eum/"
}

email {
  smtp {
    from      = "notif@acmecorp.com"
    host      = "relay-1.acme.internal"
    port      = 25
    user      = "ops-notif@acmecorp.com"
    password  = "yUnoEm41l"
    use_ssl   = true
    start_tls = false
  }
}

o_auth {
  client_id     = "123456-1n574n4adgjlmnop.apps.googleusercontent.com"
  client_secret = "XNLV-fpf_deadBeEf1234"
}

proxy {
  host     = "10.9.4.13"
  port     = 8080
  user     = "anonymous"
  password = "P4ssword1234"
  non_proxyHosts = ["google.com"]
}

Enabling HSTS

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

hsts_enabled = true

Generating REST API clients

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.

Replacing existing certificates

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"
}

Custom certificates for webhook or mail integrations

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>"