Skip to content

CiscoCloud/consulacl

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

12 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

consulacl

Command line interface to the Consul ACL HTTP API. Documentation for the Consul ACL system is at the Consul ACL internals page.

Installation

You can download a released consulacl artifact from the consulacl release page on Github. If you wish to compile from source, you will need to have buildtools and Go installed:

$ git clone https://github.com/CiscoCloud/consulacl.git
$ cd consulacl
$ make

Basic Usage

usage: consulacl [--version] [--help] <command> [<args>]

Available commands are:
    clone      Create a new token from an existing one
    create     Create an ACL
    destroy    Destroy an ACL
    info       Query an ACL token
    list       List a value
    update     Update an ACL

Common arguments

Option Default Description
--consul 127.0.0.1:8500 HTTP address of the Consul Agent
--ssl false Use HTTPS while talking to Consul
--ssl-verify true Verify certificates when connecting via SSL. Requires --ssl
--ssl-cert unset Path to an SSL client certificate to use to authenticate to the consul server
--ssl-ca-cert unset Path to a CA certificate file, containing one or more CA certificates to use to validate the certificate sent by the consul server to us.
--token* unset The Consul API token.

* A management token is required for all ACL operations

clone command

Usage

consulacl clone [options] id

  Create a new token from an existing one

Example

$ consulacl clone --sll --token=b78191f9-01fb-24d0-4278-be05ee82c6c4 19933651-439e-5123-5a2f-6bdf2afa0d70
a06db641-070d-eae0-1ff8-8e8c67399fa4

create command

Usage

Usage: consulacl create [options]

  Create an ACL. Requires a management token.

Options:

  --management			Create a management token
				(default: false)
  --name			Name of the ACL
				(default: not set)
  --rule='type:path:policy'	Rule to create. Can be multiple rules on a command line
				(default: not set)

Arguments

Option Default Description
management false Create the token as a management ACL
name not set Name of the ACL
rule not set Rule to create

Multiple rules can be specified on the command line. The format for the rule is [key|service]:path:[read:write:deny]. The list of rules is converted to a JSON object:

{
  "key": {
    "<path_1>": {
      "policy": "<policy_1>"
    }, ...
   },
  "service": {
    "<path_2>": {
      "policy": "<policy_2>"
    }, ...
  }
}

An empty path attribute generates:

{
   "key": {
     "": {
       "policy": "<policy_1>"
     }
   }
}

The token id of the newly created ACL is printed on stdout on success.

Example

$ consulacl create --ssl --token=b78191f9-01fb-24d0-4278-be05ee82c6c4 \
    --rule='key:test/node:read' \
    --rule='service:hello-world:write'
25c25096-e680-2faa-d864-b9314308387a

destroy command

Usage

consulacl destroy [options] id

  Destroy an ACL

Example

$ consulacl destroy --ssl --token=b78191f9-01fb-24d0-4278-be05ee82c6c4 \
    25c25096-e680-2faa-d864-b9314308387a

info command

Usage

consulacl info [options] id

  Query information about an ACL token

Example

$ consulacl info --ssl --ssl-verify=false --token=b78191f9-01fb-24d0-4278-be05ee82c6c4 \
	 25c25096-e680-2faa-d864-b9314308387a
{
  "CreateIndex": 4100,
  "ModifyIndex": 4100,
  "ID": "25c25096-e680-2faa-d864-b9314308387a",
  "Name": "",
  "Type": "client",
  "Rules": "{\"key\":{\"test/node\":{\"Policy\":\"read\"}},\"service\":{\"hello-world\":{\"Policy\":\"write\"}}}"
}

### list command

#### Usage

```shell
consulacl list [options]

  List all active ACL tokens.

Example

$ consulacl list --ssl --token=b78191f9-01fb-24d0-4278-be05ee82c6c4 
{
  {
    "CreateIndex": 3,
    "ModifyIndex": 3,
    "ID": "anonymous",
    "Name": "Anonymous Token",
    "Type": "client",
    "Rules": ""
  },
  {
    "CreateIndex": 4100,
    "ModifyIndex": 4100,
    "ID": "25c25096-e680-2faa-d864-b9314308387a",
    "Name": "",
    "Type": "client",
    "Rules": "{\"key\":{\"test/node\":{\"Policy\":\"read\"}},\"service\":{\"hello-world\":{\"Policy\":\"write\"}}}"
  }
}

update command

The update command updates an ACL if it exists and creates a new one if it does not. All of the ACL settings are overwritten on update.

Usage

Usage: consulacl update [options] id

  Update an ACL. Will be created if it doesn't exist.

Options:

  --management			Create a management token
				(default: false)
  --name			Name of the ACL
				(default: not set)
  --rule='type:path:policy'	Rule to create. Can be multiple rules on a command line
				(default: not set)

Arguments

Option Default Description
management false Create the token as a management ACL
name not set Name of the ACL
rule not set Rule to create

Multiple rules can be specified on the command line. The format for the rule is [key|service]:path:[read:write:deny]. The list of rules is converted to a JSON object:

{
  "key": {
    "<path_1>": {
      "policy": "<policy_1>"
    }, ...
   },
  "service": {
    "<path_2>": {
      "policy": "<policy_2>"
    }, ...
  }
}

An empty path attribute generates:

{
   "key": {
     "": {
       "policy": "<policy_1>"
     }
   }
}

The token id of the newly created ACL is printed on stdout on success.

Example

$ consulacl update --ssl --token=b78191f9-01fb-24d0-4278-be05ee82c6c4 \
    --rule='key:test/node:read' \
    --rule=`key:test/node1:write' \
    --rule='service:hello-world:write' \
    25c25096-e680-2faa-d864-b9314308387a