+
+ | Operation |
+ Version <= 0.6.3 |
+ Version > 0.6.3 |
+
+
+ | Create static query without `Name` |
+ The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. |
+ No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query. |
+
+
+ | Create static query with `Name` |
+ The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. |
+ The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query. |
+
+
+ | Manage static query without `Name` |
+ The ACL Token used to create the query, or a management token must be supplied in order to perform these operations. |
+ Any client with the ID of the query can perform these operations. |
+
+
+ | Manage static query with a `Name` |
+ The ACL token used to create the query, or a management token must be supplied in order to perform these operations. |
+ Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed. |
+
+
+ | List queries |
+ A management token is required to list any queries. |
+ The client token's `query` ACL policy is used to determine which queries they can see. Only management tokens can see prepared queries without `Name`. |
+
+
+ | Execute query |
+ Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored. |
+ The captured token, client's token, or anonymous token is used to filter the results, as described above. |
+
+
+
+#### Service Rules
+
+The `service` policy controls service-level registration and read access to the [Catalog API](/api/catalog.html)
+and service discovery with the [Health API](/api/health.html).
+
+Service rules look like this:
+
+```text
+service "" {
+ policy = "read"
+}
+service "app" {
+ policy = "write"
+}
+service "admin" {
+ policy = "deny"
+}
+```
+
+Service rules are keyed by the service name prefix they apply to, using the longest prefix match rule. In
+the example above, the rules allow read-only access to any service name with the empty prefix, allow
+read-write access to any service name that starts with "app", and deny all access to any service name that
+starts with "admin".
+
+Consul's DNS interface is affected by restrictions on service rules. If the
+[`acl_token`](/docs/agent/options.html#acl_token) used by the agent does not have "read" access to a
+given service, then the DNS interface will return no records when queried for it.
+
+When reading from the catalog or retrieving information from the health endpoints, service rules are
+used to filter the results of the query.
+
+Service rules come into play when using the [Agent API](/api/agent.html) to register services or
+checks. The agent will check tokens locally as a service or check is registered, and Consul also
+performs periodic [anti-entropy](/docs/internals/anti-entropy.html) syncs, which may require an
+ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens
+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.
+
+#### Session Rules
+
+The `session` policy controls access to [Session API](/api/session.html)] operations.
+
+Session rules look like this:
+
+```text
+session "" {
+ policy = "read"
+}
+session "app" {
+ policy = "write"
+}
+session "admin" {
+ policy = "deny"
+}
+```
+
+Session rules are keyed by the node name prefix they apply to, using the longest prefix match rule. In
+the example above, the rules allow read-only access to sessions on node name with the empty prefix, allow
+creating sessions on any node name that starts with "app", and deny all access to any sessions on a node
+name that starts with "admin".
+
+## Advanced Topics
+
+
-
- | Operation |
- Version <= 0.6.3 |
- Version > 0.6.3 |
-
-
- | Create static query without `Name` |
- The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. |
- No ACL policies are used as long as no `Name` is defined. No `Token` is captured by default unless specifically supplied by the client when creating the query. |
-
-
- | Create static query with `Name` |
- The ACL Token used to create the prepared query is checked to make sure it can access the service being queried. This token is captured as the `Token` to use when executing the prepared query. |
- The client token's `query` ACL policy is used to determine if the client is allowed to register a query for the given `Name`. No `Token` is captured by default unless specifically supplied by the client when creating the query. |
-
-
- | Manage static query without `Name` |
- The ACL Token used to create the query, or a management token must be supplied in order to perform these operations. |
- Any client with the ID of the query can perform these operations. |
-
-
- | Manage static query with a `Name` |
- The ACL token used to create the query, or a management token must be supplied in order to perform these operations. |
- Similar to create, the client token's `query` ACL policy is used to determine if these operations are allowed. |
-
-
- | List queries |
- A management token is required to list any queries. |
- The client token's `query` ACL policy is used to determine which queries they can see. Only management tokens can see prepared queries without `Name`. |
-
-
- | Execute query |
- Since a `Token` is always captured when a query is created, that is used to check access to the service being queried. Any token supplied by the client is ignored. |
- The captured token, client's token, or anonymous token is used to filter the results, as described above. |
-
-
-