Configuring Instana backend on Docker

Creating a template for the settings.hcl file

The settings.hcl file is generated during the installation process.

If required, run the command instana settings template to create a settings.hcl file with default (empty) values.

Default configuration

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

Data directories

Instana defaults to the following directory structures.

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

Datastore credentials

All data stores require authentication. The configuration of the credentials is optional. Credentials that are not specified are initially generated and added to the settings.hcl file. Passwords can be changed by updating them in the settings.hcl file. Changes are applied by running instana update.

Note: 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
}

Notifications server settings

See the following settings:

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

Proxy settings

See the following settings:

proxy {
  host     = "10.9.4.13"
  port     = 8080
  user     = "anonymous"
  password = "P4ssword1234"
}

Docker repository settings

See the following settings:

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

OAuth settings

See the following settings:

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

End-user monitoring (EUM) settings

See the following settings:

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

Enabling HSTS

To enable 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 detailed information about how to configure REST API clients, see Web REST API docs.

Enabling audit logging

To configure an audit logger that logs each login to the Instana system, the following config toggle must be activated at root level in settings.hcl. Then, the system must be updated by running the command instana update -f /path/to/settings.hcl. The new log file can be found in the following path in the log directory /instana/butler/audit.log.

toggle "config.audit.log.level" {
  value = "info"
}

Replacing existing certificates

To replace existing certificates with other certificates, update paths to your certificate files in the settings.hcl file. Then, the system must be updated by running the 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 webhook with a custom certificate, you can provide a custom Java™ keystore (jssecacerts) that contains your certificate for JVMs.

1. Copy a current JVM keystore from your JVM $JAVA_HOME/lib/security/cacerts.
2. Import your custom cert 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. Now you must add the absolute path of the keystore by using the configuration key `custom_keystore` in the `settings.hcl` file.
   
   ``` {: codeblock}
   custom_keystore="<path_to_javakeystore>"