From 3c97406042bc981437f308020795a4863e54fd28 Mon Sep 17 00:00:00 2001
From: Daniel Nelson <daniel@wavesofdawn.com>
Date: Thu, 27 Dec 2018 13:12:00 -0800
Subject: [PATCH] Improve config file environment variable documentation
 (#5200)

---
 docs/CONFIGURATION.md | 40 ++++++++++++++++++++++++++++++++++++++--
 1 file changed, 38 insertions(+), 2 deletions(-)

diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md
index 6bb6c2e09919c..0b2c271565a2b 100644
--- a/docs/CONFIGURATION.md
+++ b/docs/CONFIGURATION.md
@@ -24,12 +24,48 @@ telegraf --input-filter cpu:mem:net:swap --output-filter influxdb:kafka config
 ### Environment Variables
 
 Environment variables can be used anywhere in the config file, simply prepend
-them with $. For strings the variable must be within quotes (ie, "$STR_VAR"),
-for numbers and booleans they should be plain (ie, $INT_VAR, $BOOL_VAR)
+them with `$`.  Replacement occurs before file parsing.   For strings
+the variable must be within quotes, e.g., `"$STR_VAR"`, for numbers and booleans
+they should be unquoted, e.g., `$INT_VAR`, `$BOOL_VAR`.
 
 When using the `.deb` or `.rpm` packages, you can define environment variables
 in the `/etc/default/telegraf` file.
 
+**Example**:
+
+`/etc/default/telegraf`:
+```
+USER="alice"
+INFLUX_URL="http://localhost:8086"
+INFLUX_SKIP_DATABASE_CREATION="true"
+INFLUX_PASSWORD="monkey123"
+```
+
+`/etc/telegraf.conf`:
+```toml
+[global_tags]
+  user = "$USER"
+
+[[inputs.mem]]
+
+[[outputs.influxdb]]
+  urls = ["$INFLUX_URL"]
+  skip_database_creation = $INFLUX_SKIP_DATABASE_CREATION
+  password = "$INFLUX_PASSWORD"
+```
+
+The above files will produce the following effective configuration file to be
+parsed:
+```toml
+[global_tags]
+  user = "alice"
+
+[[outputs.influxdb]]
+  urls = "http://localhost:8086"
+  skip_database_creation = true
+  password = "monkey123"
+```
+
 ### Configuration file locations
 
 The location of the configuration file can be set via the `--config` command