//////////////////////////////////////////////////////////////////////////
//// This content is shared by all Elastic Beats. Make sure you keep the
//// descriptions here generic enough to work for all Beats that include
//// this file. When using cross references, make sure that the cross
//// references resolve correctly for any files that include this one.
//// Use the appropriate variables defined in the index.asciidoc file to
//// resolve Beat names: beatname_uc and beatname_lc.
//// Use the following include to pull this content into a doc file:
//// include::../../libbeat/docs/shared-env-vars.asciidoc[]
//////////////////////////////////////////////////////////////////////////

[[using-environ-vars]]
== Using Environment Variables in the Configuration

experimental[]

You can use environment variable references in the +{beatname_lc}.yml+ file to
set values that need to be configurable during deployment. To do this, use:

`${VAR}`

Where `VAR` is the name of the environment variable.

Each variable reference is replaced at startup by the value of the environment
variable. The replacement is case-sensitive and occurs before the YAML file is
parsed. References to undefined variables are replaced by empty strings unless
you specify a default value. To specify a default value, use:

`${VAR:default_value}`

Where `default_value` is the value to use if the environment variable is
undefined.

If you need to use a literal `${` in your configuration file then you can write
`$${` to escape the expansion.

After changing the value of an environment variable, you need to restart
{beatname_uc} to pick up the new value.

[float]
=== Examples

Here are some examples of configurations that use environment variables
and what each configuration looks like after replacement:

[options="header"]
|==================================
|Config source	       |Environment setting   |Config after replacement
|`name: ${NAME}`       |`export NAME=elastic` |`name: elastic`
|`name: ${NAME}`       |no setting            |`name:`
|`name: ${NAME:beats}` |no setting            |`name: beats`
|`name: ${NAME:beats}` |`export NAME=elastic` |`name: elastic`
|==================================
