Merge pull request hashicorp#3928 from hashicorp/service-token-docs

Notes on ACL token storage and permissions

website/source/docs/agent/options.html.md

@@ -131,13 +131,19 @@ will exit with an error at startup.
   either "json" or "hcl" forces Consul to interpret any file with or without
   extension to be interpreted in that format.
 
-* <a name="_data_dir"></a><a href="#_data_dir">`-data-dir`</a> - This flag provides
-  a data directory for the agent to store state.
-  This is required for all agents. The directory should be durable across reboots.
-  This is especially critical for agents that are running in server mode as they
-  must be able to persist cluster state. Additionally, the directory must support
-  the use of filesystem locking, meaning some types of mounted folders (e.g. VirtualBox
-  shared folders) may not be suitable.
+* <a name="_data_dir"></a><a href="#_data_dir">`-data-dir`</a> - This flag
+  provides a data directory for the agent to store state. This is required for
+  all agents. The directory should be durable across reboots. This is especially
+  critical for agents that are running in server mode as they must be able to
+  persist cluster state. Additionally, the directory must support the use of
+  filesystem locking, meaning some types of mounted folders (e.g. VirtualBox
+  shared folders) may not be suitable. **Note:** both server and non-server
+  agents may store ACL tokens in the state in this directory so read access may
+  grant access to any tokens on servers and to any tokens used during service
+  registration on non-servers. On Unix-based platforms the files are written
+  with 0600 permissions so you should ensure only trusted processes can execute
+  as the same user as Consul. On Windows, you should ensure the directory has
+  suitable permissions configured as these will be inherited.
 
 * <a name="_datacenter"></a><a href="#_datacenter">`-datacenter`</a> - This flag controls the datacenter in
   which the agent is running. If not provided,

website/source/docs/guides/acl.html.md

@@ -961,12 +961,16 @@ to use for registration events:
 1. Using the [acl_token](/docs/agent/options.html#acl_token) configuration
    directive. This allows a single token to be configured globally and used
    during all service and check registration operations.
-2. Providing an ACL token with service and check definitions at
-   registration time. This allows for greater flexibility and enables the use
-   of multiple tokens on the same agent. Examples of what this looks like are
-   available for both [services](/docs/agent/services.html) and
-   [checks](/docs/agent/checks.html). Tokens may also be passed to the
-   [HTTP API](/api/index.html) for operations that require them.
+2. Providing an ACL token with service and check definitions at registration
+   time. This allows for greater flexibility and enables the use of multiple
+   tokens on the same agent. Examples of what this looks like are available for
+   both [services](/docs/agent/services.html) and
+   [checks](/docs/agent/checks.html). Tokens may also be passed to the [HTTP
+   API](/api/index.html) for operations that require them. **Note:** all tokens
+   passed to an agent are persisted on local disk to allow recovery from
+   restarts. See [`-data-dir` flag
+   documentation](/docs/agent/options.html#acl_token) for notes on securing
+   access.
 
 In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with
 [`enable_script_checks`](/docs/agent/options.html#_enable_script_checks) set to `true` in order to enable