github.com/outbrain/consul@v1.4.5/website/source/docs/commands/acl/acl-policy.html.md.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: ACL Policy Management"
     4  sidebar_current: "docs-commands-acl-policy"
     5  ---
     6  
     7  # Consul ACL Policies
     8  
     9  Command: `consul acl policy`
    10  
    11  The `acl policy` command is used to manage Consul's ACL policies. There are
    12  subcommands for the individual operations that can be performed.
    13  
    14  * [`create`](#create)
    15  * [`read`](#read)
    16  * [`update`](#update)
    17  * [`delete`](#delete)
    18  * [`list`](#list)
    19  
    20  ACL policies are also accessible via the [HTTP API](/api/acl/acl.html).
    21  
    22  Usage: `consul acl policy <subcommand> [options] [args]`
    23  
    24  -> **Note:** All of the examples show for the subcommands will require a valid Consul token with the appropriate permissions.
    25  Either set the `CONSUL_HTTP_TOKEN` environment variable to the tokens secret ID or pass the secret ID as the value of the `-token`
    26  parameter.
    27  
    28  ## Identitying Polices
    29  
    30  In several of the subcommands a policy will have to be identified to be read, modified or deleted. Those subcommands support
    31  specifying the policy by its ID using the `-id` parameter or by name using the `-name` parameter. When specifying the policy
    32  by its ID a unique policy ID prefix may be specified instead of the entire UUID. As long as it is unique it will be resolved
    33  to the full UUID and used. Additionally builtin policy names will be accepted as the value to the `-id` parameter. Even if
    34  the builtin policies are renamed their original name can be used to operate on them.
    35  
    36  Builtin Policies:
    37  
    38  | Policy UUID                          | Policy Name       |
    39  | ------------------------------------ | ----------------- |
    40  | 00000000-0000-0000-0000-000000000001 | global-management |
    41  
    42  ## Common Subcommand Options
    43  
    44  All of the `consul acl policy` subcommands support the following options:
    45  
    46  <%= partial "docs/commands/http_api_options_client" %>
    47  <%= partial "docs/commands/http_api_options_server" %>
    48  
    49  ## `create`
    50  
    51  Command: `consul acl policy create`
    52  
    53  This command creates new policies. The policies rules can either be set explicitly or the
    54  `-from-token` parameter may be used to load the rules from a legacy ACL token. When loading
    55  the rules from an existing legacy ACL token, the rules get translated from the legacy syntax
    56  to the new syntax.
    57  
    58  Both the `-rules` and `-from-token` parameter values allow loading the value
    59  from stdin, a file or the raw value. To use stdin pass `-` as the value.
    60  To load the value from a file prefix the value with an `@`. Any other
    61  values will be used directly.
    62  
    63  -> **Deprecated:** The `-from-token` and `-token-secret` arguments exist only as a convenience
    64  to make legacy ACL migration easier. These will be removed in a future major release when
    65  support for the legacy ACL system is removed.
    66  
    67  ### Usage
    68  
    69  Usage: `consul acl policy create [options] [args]`
    70  
    71  #### Options
    72  
    73  * [Common Subcommand Options](#common-subcommand-options)
    74  
    75  * `-description=<string>` - A description of the policy.
    76  
    77  * `-from-token=<string>` - The legacy token to retrieve the rules for when creating this
    78     policy. When this is specified no other rules should be given.
    79     Similar to the -rules option the token to use can be loaded from
    80     stdin or from a file.
    81  
    82  * `-meta` - Indicates that policy metadata such as the content hash and raft
    83     indices should be shown for each entry.
    84  
    85  * `-name=<string>` - The new policy's name. This flag is required.
    86  
    87  * `-rules=<string>` - The policy rules. May be prefixed with '@' to indicate that the
    88     value is a file path to load the rules from. '-' may also be given
    89     to indicate that the rules are available on stdin.
    90  
    91  * `-token-secret` - Indicates the token provided with -from-token is a SecretID and not
    92     an AccessorID.
    93  
    94  * `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
    95     This flag may be specified multiple times.
    96  
    97  
    98  ### Examples
    99  
   100  Create a new policy that is valid in all datacenters:
   101  
   102  ```sh
   103  $ consul acl policy create -name "acl-replication" -description "Policy capable of replicating ACL policies" -rules 'acl = "read"'
   104  ID:           35b8ecb0-707c-ee18-2002-81b238b54b38
   105  Name:         acl-replication
   106  Description:  Policy capable of replicating ACL policies
   107  Datacenters:
   108  Rules:
   109  acl = "read"
   110  ```
   111  
   112  Create a new policy valid only in specific datacenters with rules read from a file:
   113  
   114  ```sh
   115  $ consul acl policy create -name "replication" -description "Replication" -rules @rules.hcl -valid-datacenter dc1 -valid-datacenter dc2
   116  ID:           ca44555b-a2d8-94de-d763-88caffdaf11f
   117  Name:         replication
   118  Description:  Replication
   119  Datacenters:  dc1, dc2
   120  Rules:
   121  acl = "read"
   122  service_prefix "" {
   123     policy = "read"
   124     intentions = "read"
   125  }
   126  ```
   127  
   128  Create a new policy with rules equivalent to that of a legacy ACL token:
   129  
   130  ```sh
   131  $ consul acl policy create -name "node-services-read" -from-token 5793a5ce -description "Can read any node and service"
   132  ID:           06acc965-df4b-5a99-58cb-3250930c6324
   133  Name:         node-services-read
   134  Description:  Can read any node and service
   135  Datacenters:
   136  Rules:
   137  service_prefix "" {
   138    policy = "read"
   139  }
   140  
   141  node_prefix "" {
   142    policy = "read"
   143  }
   144  
   145  ```
   146  
   147  ## `read`
   148  
   149  Command: `consul acl policy read`
   150  
   151  This command reads and displays a policies details.
   152  
   153  ### Usage
   154  
   155  Usage: `consul acl policy read [options] [args]`
   156  
   157  #### Options
   158  
   159  * [Common Subcommand Options](#common-subcommand-options)
   160  
   161  * `-id=<string>` - The ID of the policy to read. It may be specified as a unique ID
   162     prefix but will error if the prefix matches multiple policy IDs.
   163  
   164  * `-meta` - Indicates that policy metadata such as the content hash and raft
   165    indices should be shown for each entry.
   166  
   167  * `-name=<string>` - The name of the policy to read.
   168  
   169  ### Examples
   170  
   171  Get policy details:
   172  
   173  ```sh
   174  $ consul acl policy read -id 00000000-0000-0000-0000-000000000001
   175  ID:           00000000-0000-0000-0000-000000000001
   176  Name:         global-management
   177  Description:  Builtin Policy that grants unlimited access
   178  Datacenters:
   179  Rules:
   180  
   181  acl = "write"
   182  agent_prefix "" {
   183     policy = "write"
   184  }
   185  event_prefix "" {
   186     policy = "write"
   187  }
   188  key_prefix "" {
   189     policy = "write"
   190  }
   191  keyring = "write"
   192  node_prefix "" {
   193     policy = "write"
   194  }
   195  operator = "write"
   196  query_prefix "" {
   197     policy = "write"
   198  }
   199  service_prefix "" {
   200     policy = "write"
   201     intentions = "write"
   202  }
   203  session_prefix "" {
   204     policy = "write"
   205  }
   206  ```
   207  
   208  Get policy details by name:
   209  
   210  ```sh
   211  $ consul acl policy read -name "acl-replication"
   212  ID:           35b8ecb0-707c-ee18-2002-81b238b54b38
   213  Name:         acl-replication
   214  Description:  Token capable of replicating ACL policies
   215  Datacenters:
   216  Rules:
   217  acl = "read"
   218  ```
   219  
   220  Get policy details (Builtin Policies):
   221  
   222  Builtin policies can be accessed by specifying their original name as the value to the `-id` parameter.
   223  
   224  ```sh
   225  $ consul acl policy read -id global-management
   226  ID:           00000000-0000-0000-0000-000000000001
   227  Name:         global-management
   228  Description:  Builtin Policy that grants unlimited access
   229  Datacenters:
   230  Hash:         b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69
   231  Create Index: 4
   232  Modify Index: 4
   233  Rules:
   234  
   235  acl = "write"
   236  agent_prefix "" {
   237     policy = "write"
   238  }
   239  event_prefix "" {
   240     policy = "write"
   241  }
   242  key_prefix "" {
   243     policy = "write"
   244  }
   245  keyring = "write"
   246  node_prefix "" {
   247     policy = "write"
   248  }
   249  operator = "write"
   250  query_prefix "" {
   251     policy = "write"
   252  }
   253  service_prefix "" {
   254     policy = "write"
   255     intentions = "write"
   256  }
   257  session_prefix "" {
   258     policy = "write"
   259  }
   260  ```
   261  
   262  ## `update`
   263  
   264  Command: `consul acl policy update`
   265  
   266  This command is used to update a policy. The default operations is to merge the current policy
   267  with those values provided to the command invocation. Therefore to update just one field, only
   268  the `-id` or `-name` options and the option to modify must be provided. Note that renaming
   269  policies requires both the `-id` and `-name` as the new name cannot yet be used to lookup the
   270  policy.
   271  
   272  ### Usage
   273  
   274  Usage: `consul acl policy update [options] [args]`
   275  
   276  #### Options
   277  
   278  * [Common Subcommand Options](#common-subcommand-options)
   279  
   280  * `-description=<string>` - A description of the policy.
   281  
   282  * `-id=<string>` - The ID of the policy to update. It may be specified as a
   283     unique ID prefix but will error if the prefix matches multiple policy IDs
   284  
   285  * `-meta` - Indicates that policy metadata such as the content hash and raft
   286    indices should be shown for each entry
   287  
   288  * `-name=<string>` - The policies name.
   289  
   290  * `-no-merge` - Do not merge the current policy information with what is provided
   291     to the command. Instead overwrite all fields with the exception of
   292     the policy ID which is immutable.
   293  
   294  * `-rules=<string>` - The policy rules. May be prefixed with `@` to indicate that
   295     the value is a file path to load the rules from. `-` may also be given to
   296     indicate that the rules are available on stdin.
   297  
   298  * `-valid-datacenter=<value>` - Datacenter that the policy should be valid within.
   299     This flag may be specified multiple times.
   300  
   301  ### Examples
   302  
   303  Update a policy:
   304  
   305  ```sh
   306  $ consul acl policy update -id 35b8 -name "replication" -description "Policy capable of replication ACL policies and Intentions" -rules @rules.hcl
   307  Policy updated successfully
   308  ID:           35b8ecb0-707c-ee18-2002-81b238b54b38
   309  Name:         replication
   310  Description:  Policy capable of replication ACL policies and Intentions
   311  Datacenters:
   312  Rules:
   313  acl = "read"
   314  
   315  service_prefix "" {
   316     policy = "read"
   317     intentions = "read"
   318  }
   319  ```
   320  
   321  Rename a policy:
   322  
   323  ```sh
   324  $ consul acl policy update -id 35b8 -name "dc1-replication"
   325  Policy updated successfully
   326  ID:           35b8ecb0-707c-ee18-2002-81b238b54b38
   327  Name:         dc1-replication
   328  Description:  Policy capable of replication ACL policies and Intentions
   329  Datacenters:  dc1
   330  Rules:
   331  acl = "read"
   332  
   333  service_prefix "" {
   334     policy = "read"
   335     intentions = "read"
   336  }
   337  
   338  ```
   339  
   340  ## `delete`
   341  
   342  Command: `consul acl policy delete`
   343  
   344  This command deletes a policy. Policies may be deleted by their ID or by name.
   345  
   346  ### Usage
   347  
   348  Usage: `consul acl policy delete [options]`
   349  
   350  #### Options
   351  
   352  * [Common Subcommand Options](#common-subcommand-options)
   353  
   354  * `-id=<string>` - The ID of the policy to delete. It may be specified as a
   355     unique ID prefix but will error if the prefix matches multiple policy IDs.
   356  
   357  * `-name=<string>` - The Name of the policy to delete.
   358  
   359  ### Examples
   360  
   361  Delete a policy:
   362  
   363  ```sh
   364  $ consul acl policy delete -id 35b8
   365  Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully
   366  ```
   367  
   368  Delete a policy by name:
   369  
   370  ```sh
   371  $ consul acl policy delete -name acl-replication
   372  Policy "35b8ecb0-707c-ee18-2002-81b238b54b38" deleted successfully
   373  ```
   374  
   375  ## `list`
   376  
   377  Command: `consul acl policy list`
   378  
   379  This command lists all policies. By default it will not show metadata.
   380  
   381  ### Usage
   382  
   383  Usage: `consul acl policy list`
   384  
   385  #### Options
   386  
   387  * [Common Subcommand Options](#common-subcommand-options)
   388  
   389  * `-meta` - Indicates that policy metadata such as the content hash and
   390     Raft indices should be shown for each entry.
   391  
   392  ### Examples
   393  
   394  Default listing.
   395  
   396  ```sh
   397  $ consul acl policy list
   398  global-management:
   399     ID:           00000000-0000-0000-0000-000000000001
   400     Description:  Builtin Policy that grants unlimited access
   401     Datacenters:
   402  acl-replication:
   403     ID:           35b8ecb0-707c-ee18-2002-81b238b54b38
   404     Description:  Policy capable of replicating ACL policies
   405     Datacenters:
   406  ```
   407  
   408  Show Metadata.
   409  
   410  ```sh
   411  $ consul acl policy list -meta
   412  global-management:
   413     ID:           00000000-0000-0000-0000-000000000001
   414     Description:  Builtin Policy that grants unlimited access
   415     Datacenters:
   416     Hash:         b30210b7aba9facd1c57891e3df27669174a08b690cb2905e0797535f75eba69
   417     Create Index: 4
   418     Modify Index: 4
   419  node-services-read:
   420     ID:           06acc965-df4b-5a99-58cb-3250930c6324
   421     Description:  Can read any node and service
   422     Datacenters:
   423     Hash:         19d2a73dcd315506af73bfff1492779a0dc0235066fcac07f432fb2cc3402133
   424     Create Index: 244
   425     Modify Index: 244
   426  acl-replication:
   427     ID:           ca44555b-a2d8-94de-d763-88caffdaf11f
   428     Description:  Token capable of replicating ACL policies
   429     Datacenters:  dc1, dc2
   430     Hash:         b94669679cc24e0d064412e4aa90b470b7f900a8e0801f65feaf1f7d716a5390
   431     Create Index: 198
   432     Modify Index: 198
   433  ```