This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
« Accessing event data and fields Sending data to Elastic Cloud (hosted Elasticsearch Service) »
Elastic Docs ›Logstash Reference [master] ›Creating a Logstash pipeline

Using environment variables

edit

Using environment variables

edit

Overview

edit
  • You can set environment variable references in the configuration for Logstash plugins by using ${var}.
  • At Logstash startup, each reference is 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 for list-type URI parameters can support lists of space-delimited values. Currently, other non-URI based options do not support lists of values. See Cross-plugin concepts and features
  • Environment variables are immutable. If you update the environment variable, you’ll have to restart Logstash to pick up the updated value.

Examples

edit

These 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 this 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 this 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 Sending data to Elastic Cloud (hosted Elasticsearch Service) »