IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Accessing event data and fields in the configuration Logstash configuration examples »

› ›

Using environment variables in the configuration

edit

Using environment variables in the configuration

edit

Overview

edit

You can set environment variable references in the configuration for Logstash plugins by using ${var}.
At Logstash startup, each reference will be replaced by the value of the environment variable.
The replacement is case-sensitive.
References to undefined variables raise a Logstash configuration error.
You can give a default value by using the form ${var:default value}. Logstash uses the default value if the environment variable is undefined.
You can add environment variable references in any plugin option type : string, number, boolean, array, or hash.
Environment variables are immutable. If you update the environment variable, you’ll have to restart Logstash to pick up the updated value.

Examples

edit

The following examples show you how to use environment variables to set the values of some commonly used configuration options.

Setting the TCP port

edit

Here’s an example that uses an environment variable to set the TCP port:

input {
  tcp {
    port => "${TCP_PORT}"
  }
}

Now let’s set the value of TCP_PORT:

export TCP_PORT=12345

At startup, Logstash uses the following configuration:

input {
  tcp {
    port => 12345
  }
}

If the TCP_PORT environment variable is not set, Logstash returns a configuration error.

You can fix this problem by specifying a default value:

input {
  tcp {
    port => "${TCP_PORT:54321}"
  }
}

Now, instead of returning a configuration error if the variable is undefined, Logstash uses the default:

input {
  tcp {
    port => 54321
  }
}

If the environment variable is defined, Logstash uses the value specified for the variable instead of the default.

Setting the value of a tag

edit

Here’s an example that uses an environment variable to set the value of a tag:

filter {
  mutate {
    add_tag => [ "tag1", "${ENV_TAG}" ]
  }
}

Let’s set the value of ENV_TAG:

export ENV_TAG="tag2"

At startup, Logstash uses the following configuration:

filter {
  mutate {
    add_tag => [ "tag1", "tag2" ]
  }
}

Setting a file path

edit

Here’s an example that uses an environment variable to set the path to a log file:

filter {
  mutate {
    add_field => {
      "my_path" => "${HOME}/file.log"
    }
  }
}

Let’s set the value of HOME:

export HOME="/path"

At startup, Logstash uses the following configuration:

filter {
  mutate {
    add_field => {
      "my_path" => "/path/file.log"
    }
  }
}

« Accessing event data and fields in the configuration Logstash configuration examples »