TheArchive/tailscale
1
0
Fork 0
mirror of https://github.com/tailscale/tailscale.git synced 2025-04-19 05:02:34 +00:00
Code Issues Packages Projects Releases Wiki Activity

api.md: clarify response behaviour for ACL POST endpoint

Browse Source 
Signed-off-by: Daniel Chung <daniel@tailscale.com>
This commit is contained in:
Daniel Chung 2021-01-07 12:14:52 -05:00 committed by Brad Fitzpatrick
parent a64b57e2fb
commit 5e90037f1a
1 changed files with 33 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
api.md
View File

@ -367,10 +367,11 @@ Etag: "e0b2816b418b3f266309d94426ac7668ab3c1fa87798785bf82f1085cc2f6d9c"
#### `POST /api/v2/tailnet/:tailnet/acl` - set ACL for a tailnet #### `POST /api/v2/tailnet/:tailnet/acl` - set ACL for a tailnet
Sets the ACL for the given tailnet. HuJSON and JSON are both accepted inputs. An `If-Match` header can be set to avoid missed updates. Sets the ACL for the given domain.
HuJSON and JSON are both accepted inputs.
An `If-Match` header can be set to avoid missed updates.
Returns error for invalid ACLs. Returns the updated ACL in JSON or HuJSON according to the `Accept` header on success. Otherwise, errors are returned for incorrectly defined ACLs, ACLs with failing tests on attempted updates, and mismatched `If-Match` header and ETag.
Returns error if using an `If-Match` header and the ETag does not match.
##### Parameters ##### Parameters
@ -380,7 +381,17 @@ Returns error if using an `If-Match` header and the ETag does not match.
`Accept` - Sets the return type of the updated ACL. Response is parsed `JSON` if `application/json` is explicitly named, otherwise HuJSON will be returned. `Accept` - Sets the return type of the updated ACL. Response is parsed `JSON` if `application/json` is explicitly named, otherwise HuJSON will be returned.
###### POST Body ###### POST Body
ACL JSON or HuJSON (see https://tailscale.com/kb/1018/acls)
The POST body should be a JSON or [HuJSON](https://github.com/tailscale/hujson#hujson---human-json) formatted JSON object.
An ACL policy may contain the following top-level properties:
* `Groups` - Static groups of users which can be used for ACL rules.
* `Hosts` - Hostname aliases to use in place of IP addresses or subnets.
* `ACLs` - Access control lists.
* `TagOwners` - Defines who is allowed to use which tags.
* `Tests` - Run on ACL updates to check correct functionality of defined ACLs.
See https://tailscale.com/kb/1018/acls for more information on those properties.
##### Example ##### Example
``` ```
@ -411,7 +422,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
}' }'
``` ```
Response Response:
``` ```
// Example/default ACLs for unrestricted connections. // Example/default ACLs for unrestricted connections.
{ {
@ -436,9 +447,25 @@ Response
} }
``` ```
Failed test error response:
```
{
"message": "test(s) failed",
"data": [
{
"user": "user1@example.com",
"errors": [
"address \"user2@example.com:400\": want: Accept, got: Drop"
]
}
]
}
```
<a name=tailnet-acl-preview-post></a> <a name=tailnet-acl-preview-post></a>
#### `POST /api/v2/tailnet/:tailnet/acl/preview` - preview rule matches on an ACL for a resource #### `POST /api/v2/tailnet/:tailnet/acl/preview` - preview rule matches on an ACL for a resource
Determines what rules match for a user on an ACL without saving the ACL to the server. Determines what rules match for a user on an ACL without saving the ACL to the server.
##### Parameters ##### Parameters
@ -477,7 +504,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl?user=user1@exampl
}' }'
``` ```
Response Response:
``` ```
{"matches":[{"users":["*"],"ports":["*:*"],"lineNumber":19}],"user":"user1@example.com"} {"matches":[{"users":["*"],"ports":["*:*"],"lineNumber":19}],"user":"user1@example.com"}
``` ```