docs: add documentation for the secrets module

Update the documentation for all relevant options that may
be resolved from secrets.

Signed-off-by:  Eric Calalahan <arksine.code@gmail.com>

README.md

@@ -43,7 +43,7 @@ to see if any action is necessary on their part.  The date of the most
 recent change is included.
 
 Users:\
-[user_changes.md](https://moonraker.readthedocs.io/en/latest/user_changes/) - November 7th 2021
+[user_changes.md](https://moonraker.readthedocs.io/en/latest/user_changes/) - December 24th 2021
 
 Developers:\
 [api_changes.md](https://moonraker.readthedocs.io/en/latest/api_changes/) - March 15th 2021

docs/configuration.md

@@ -529,10 +529,12 @@ address:
 #   A valid ip address or hostname for the shelly device.  This parameter
 #   must be provided.
 user:
-#   A user name to use for request authentication.  If no password is set
+#   A user name to use for request authentication.  This option accepts
-#   the the default is no user, otherwise the default is "admin".
+#   Jinja2 Templates, see the [secrets] section for details.  If no password
+#   is set the the default is no user, otherwise the default is "admin".
 password:
-#   The password to use for request authentication.  The default is no
+#   The password to use for request authentication.  This option accepts
+#   Jinja2 Templates, see the [secrets] section for details. The default is no
 #   password.
 output_id:
 #   The output_id (or relay id) to use if the Shelly device supports
@@ -574,9 +576,13 @@ device:
 #   "ID" in the "advanced information" section.  This parameter must be
 #   provided.
 user:
-#   The user name for request authentication.  This default is "admin".
+#   The user name for request authentication.  This option accepts
+#   Jinja2 Templates, see the [secrets] section for details.  This
+#   default is "admin".
 password:
-#   The password for request authentication.  The default is no password.
+#   The password for request authentication.  This option accepts
+#   Jinja2 Templates, see the [secrets] section for details. The
+#   default is no password.
 #
 ```
 
@@ -597,7 +603,9 @@ port:
 device:
 #   The device ID of the switch to control. This parameter must be provided.
 token:
-#   A token used for request authorization.  This paramter must be provided.
+#   A token used for request authorization.  This option accepts
+#   Jinja2 Templates, see the [secrets] section for details. This paramter
+#   must be provided.
 domain:
 #   The class of device managed by Home Assistant. Default is "switch".
 status_delay: 1.0
@@ -632,9 +640,13 @@ address:
 #   A valid ip address or hostname for the Loxone server.  This
 #   parameter must be provided.
 user:
-#  The user name used for request authorization.  The default is "admin".
+#   The user name used for request authorization.  This option accepts
+#   Jinja2 Templates, see the [secrets] section for details. The default is
+#   "admin".
 password:
-#  The password used for request authorization.  The default is "admin".
+#   The password used for request authorization.  This option accepts
+#   Jinja2 Templates, see the [secrets] section for details. The default
+#   is "admin".
 output_id:
 #   The name of a programmed output, virtual input or virtual
 #   output in the loxone configuration.  The default is no output id.
@@ -981,9 +993,15 @@ address:
 port:
 #   Port the Broker is listening on.  Default is 1883.
 username:
-#   An optional username used to log in to the Broker.  Default is no
+#   An optional username used to log in to the Broker.  This option accepts
-#   username (an anonymous login will be attempted)
+#   Jinja2 Templates, see the [secrets] section for details. The default is
+#   no username (an anonymous login will be attempted).
+password:
+#   An optional password used to log in to the Broker.  This option accepts
+#   Jinja2 Templates, see the [secrets] section for details.  The default is
+#   no password.
 password_file:
+#   *** DEPRECATED - Use the "password" option ***
 #   An optional path to a text file containing a password used to log in
 #   to the broker.  It is strongly recommended that this file be located
 #   in a folder not served by Moonraker.  It is also recommended that the
@@ -1175,6 +1193,96 @@ easily detect and use Moonraker instances.
 [zeroconf]
 ```
 
+### `[secrets]`
+
+Retreives credentials and other information from a "secrets" file
+separate from `moonraker.conf`.  This allows users to safely distribute
+their configuration and log files without revealing credentials and
+other sensitive information.
+
+```ini
+# moonraker.conf
+
+[secrets]
+secrets_path:
+#   A valid path to the "secrets" file.  A secrets file should either be
+#   in "ini" format (ie: the same format as moonraker.conf) or "json"
+#   format.  If the file is a "json" file, the top level item must be
+#   an Object.  When this parameter is not specified no file will be
+#   loaded.
+```
+
+!!! Warning
+    For maximum security the secrets file should be located in a folder
+    not served by Moonraker.
+
+Example ini file:
+
+```ini
+# moonraker_secrets.ini
+
+[mqtt_credentials]
+username: mqtt_user
+password: my_mqtt_password
+
+[home_assistant]
+token: long_token_string
+
+```
+
+Example json file:
+
+```json
+{
+    "mqtt_credentials": {
+        "username": "mqtt_user",
+        "password": "my_mqtt_password"
+    },
+    "home_assistant" {
+      "token": "long_token_string"
+    }
+}
+```
+
+!!! Tip
+    Generally speaking `ini` files are easier to manually edit.  However,
+    options are limited to string values without parsing and converting.
+    The strength of `json` is that a field may be an integer, string,
+    float, boolean, array, or object.
+
+#### Accessing secret credentials
+
+The `secrets` object is added to Moonraker's Jinja2 environment as a
+global, thus it is available in all templates. All options in
+Moonraker's configuration that accept credentials support templates.
+
+MQTT configuration example with secret credentaials:
+
+```ini
+[mqtt]
+address: mqtt-broker.local
+port: 1883
+# The username and password options below may be templates that
+# we can use to resolve stored secrets
+username: {secrets.mqtt_credentials.username}
+password: {secrets.mqtt_credentials.password}
+enable_moonraker_api: True
+```
+
+Home Assistant Switch Example:
+
+```ini
+# moonraker.conf
+
+[power homeassistant_switch]
+type: homeassistant
+address: home-assistant-host.local
+port: 8123
+device: switch.1234567890abcdefghij
+# The token option may be a template
+token: {secrets.home_assistant.token}
+domain: switch
+```
 
 ## Jinja2 Templates
 

docs/user_changes.md

@@ -2,6 +2,11 @@
 This file will track changes that require user intervention,
 such as a configuration change or a reinstallation.
 
+### December 24th 2021
+- The `password_file` option in the `[mqtt]` section has been deprecated.
+  Use the `password` option instead.  This option may be a template, thus
+  can resolve secrets stored in the `[secrets]` module.
+
 ### November 7th 2021
 - Previously all core components received configuration through
   the `[server]` config section.  As Moonraker's core functionality