config: document acl options

agent/config/runtime.go

@@ -19,8 +19,15 @@ import (
 // from files, flags and/or environment variables.
 type RuntimeConfig struct {
 	// non-user configurable values
-	AEInterval                 time.Duration
+	AEInterval time.Duration
-	ACLDisabledTTL             time.Duration
+
+	// ACLDisabledTTL is used by clients to determine how long they will
+	// wait to check again with the servers if they discover ACLs are not
+	// enabled. (not user configurable)
+	//
+	// hcl: acl_disabled_ttl = "duration"
+	ACLDisabledTTL time.Duration
+
 	CheckDeregisterIntervalMin time.Duration
 	CheckReapInterval          time.Duration
 	SegmentLimit               int
@@ -48,17 +55,85 @@ type RuntimeConfig struct {
 	ConsulSerfWANSuspicionMult       int
 	ConsulServerHealthInterval       time.Duration
 
-	ACLAgentMasterToken    string
+	// ACLAgentMasterToken is a special token that has full read and write
-	ACLAgentToken          string
+	// privileges for this agent, and can be used to call agent endpoints
-	ACLDatacenter          string
+	// when no servers are available.
-	ACLDefaultPolicy       string
+	//
-	ACLDownPolicy          string
+	// hcl: acl_agent_master_token = string
-	ACLEnforceVersion8     bool
+	ACLAgentMasterToken string
+
+	// ACLAgentToken is the default token used to make requests for the agent
+	// itself, such as for registering itself with the catalog. If not
+	// configured, the 'acl_token' will be used.
+	//
+	// hcl: acl_agent_token = string
+	ACLAgentToken string
+
+	// ACLDatacenter is the central datacenter that holds authoritative
+	// ACL records. This must be the same for the entire cluster.
+	// If this is not set, ACLs are not enabled. Off by default.
+	//
+	// hcl: acl_datacenter = string
+	ACLDatacenter string
+
+	// ACLDefaultPolicy is used to control the ACL interaction when
+	// there is no defined policy. This can be "allow" which means
+	// ACLs are used to black-list, or "deny" which means ACLs are
+	// white-lists.
+	//
+	// hcl: acl_default_policy = ("allow"|"deny")
+	ACLDefaultPolicy string
+
+	// ACLDownPolicy is used to control the ACL interaction when we cannot
+	// reach the ACLDatacenter and the token is not in the cache.
+	// There are two modes:
+	//   * allow - Allow all requests
+	//   * deny - Deny all requests
+	//   * extend-cache - Ignore the cache expiration, and allow cached
+	//                    ACL's to be used to service requests. This
+	//                    is the default. If the ACL is not in the cache,
+	//                    this acts like deny.
+	//
+	// hcl: acl_down_policy = ("allow"|"deny"|"extend-cache")
+	ACLDownPolicy string
+
+	// ACLEnforceVersion8 is used to gate a set of ACL policy features that
+	// are opt-in prior to Consul 0.8 and opt-out in Consul 0.8 and later.
+	//
+	// hcl: acl_enforce_version_8 = (true|false)
+	ACLEnforceVersion8 bool
+
+	// ACLEnableKeyListPolicy ???
+	//
+	// hcl: acl_enable_key_list_policy = (true|false)
 	ACLEnableKeyListPolicy bool
-	ACLMasterToken         string
+
-	ACLReplicationToken    string
+	// ACLMasterToken is used to bootstrap the ACL system. It should be specified
-	ACLTTL                 time.Duration
+	// on the servers in the ACLDatacenter. When the leader comes online, it ensures
-	ACLToken               string
+	// that the Master token is available. This provides the initial token.
+	//
+	// hcl: acl_master_token = string
+	ACLMasterToken string
+
+	// ACLReplicationToken is used to fetch ACLs from the ACLDatacenter in
+	// order to replicate them locally. Setting this to a non-empty value
+	// also enables replication. Replication is only available in datacenters
+	// other than the ACLDatacenter.
+	//
+	// hcl: acl_replication_token = string
+	ACLReplicationToken string
+
+	// ACLTTL is used to control the time-to-live of cached ACLs . This has
+	// a major impact on performance. By default, it is set to 30 seconds.
+	//
+	// hcl: acl_ttl = "duration"
+	ACLTTL time.Duration
+
+	// ACLToken is the default token used to make requests if a per-request
+	// token is not provided. If not configured the 'anonymous' token is used.
+	//
+	// hcl: acl_token = string
+	ACLToken string
 
 	// AutopilotCleanupDeadServers enables the automatic cleanup of dead servers when new ones
 	// are added to the peer list. Defaults to true.
@@ -378,29 +453,38 @@ type RuntimeConfig struct {
 	Datacenter string
 	NodeName   string
 
-	AdvertiseAddrLAN            *net.IPAddr
+	AdvertiseAddrLAN          *net.IPAddr
-	AdvertiseAddrWAN            *net.IPAddr
+	AdvertiseAddrWAN          *net.IPAddr
-	BindAddr                    *net.IPAddr
+	BindAddr                  *net.IPAddr
-	Bootstrap                   bool
+	Bootstrap                 bool
-	BootstrapExpect             int
+	BootstrapExpect           int
-	CAFile                      string
+	CAFile                    string
-	CAPath                      string
+	CAPath                    string
-	CertFile                    string
+	CertFile                  string
-	CheckUpdateInterval         time.Duration
+	CheckUpdateInterval       time.Duration
-	Checks                      []*structs.CheckDefinition
+	Checks                    []*structs.CheckDefinition
-	ClientAddrs                 []*net.IPAddr
+	ClientAddrs               []*net.IPAddr
-	DNSAddrs                    []net.Addr
+	DNSAddrs                  []net.Addr
-	DNSPort                     int
+	DNSPort                   int
-	DataDir                     string
+	DataDir                   string
-	DevMode                     bool
+	DevMode                   bool
-	DisableAnonymousSignature   bool
+	DisableAnonymousSignature bool
-	DisableCoordinates          bool
+	DisableCoordinates        bool
-	DisableHostNodeID           bool
+	DisableHostNodeID         bool
-	DisableKeyringFile          bool
+	DisableKeyringFile        bool
-	DisableRemoteExec           bool
+	DisableRemoteExec         bool
-	DisableUpdateCheck          bool
+	DisableUpdateCheck        bool
-	DiscardCheckOutput          bool
+	DiscardCheckOutput        bool
-	EnableACLReplication        bool
+
+	// EnableACLReplication is used to turn on ACL replication when using
+	// /v1/agent/token/acl_replication_token to introduce the token, instead
+	// of setting acl_replication_token in the config. Setting the token via
+	// config will also set this to true for backward compatibility.
+	//
+	// hcl: enable_acl_replication = (true|false)
+	// todo(fs): rename to ACLEnableReplication
+	EnableACLReplication bool
+
 	EnableDebug                 bool
 	EnableScriptChecks          bool
 	EnableSyslog                bool