//////////////////////////////////////////////////////////////////////////
//// 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:
//// :standalone:
//// include::../../libbeat/docs/shared-env-vars.asciidoc[]
//// Specify :standalone: when this file is pulled into and index. When
//// the file is embedded in another file, do no specify :standalone:
//////////////////////////////////////////////////////////////////////////

ifdef::standalone[]

[[using-environ-vars]]
== Use environment variables in the configuration

endif::[]

You can use environment variable references in the config 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 or custom error text.

To specify a default value, use:

`${VAR:default_value}`

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

To specify custom error text, use:

`${VAR:?error_text}`

Where `error_text` is custom text that will be prepended to the error
message if the environment variable cannot be expanded.

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.

[NOTE]
==================================
You can also specify environment variables when you override a config
setting from the command line by using the `-E` option. For example:

`-E name=${NAME}`

==================================

[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`
|`name: ${NAME:?You need to set the NAME environment variable}`  |no setting            | None. Returns an error message that's prepended with the custom text.
|`name: ${NAME:?You need to set the NAME environment variable}`  |`export NAME=elastic` | `name: elastic`
|==================================

[float]
=== Specify complex objects in environment variables

You can specify complex objects, such as lists or dictionaries, in environment
variables by using a JSON-like syntax.

As with JSON, dictionaries and lists are constructed using `{}` and `[]`. But
unlike JSON, the syntax allows for trailing commas and slightly different string
quotation rules. Strings can be unquoted, single-quoted, or double-quoted, as a
convenience for simple settings and to make it easier for you to mix quotation
usage in the shell. Arrays at the top-level do not require brackets (`[]`).

For example, the following environment variable is set to a list:

[source,yaml]
-------------------------------------------------------------------------------
ES_HOSTS="10.45.3.2:9220,10.45.3.1:9230"
-------------------------------------------------------------------------------

You can reference this variable in the config file:

[source,yaml]
-------------------------------------------------------------------------------
output.elasticsearch:
  hosts: '${ES_HOSTS}'
-------------------------------------------------------------------------------

When {beatname_uc} loads the config file, it resolves the environment variable and
replaces it with the specified list before reading the `hosts` setting.

NOTE: Do not use double-quotes (`"`) to wrap regular expressions, or the backslash (`\`) will be interpreted as an escape character.