mirror of
https://github.com/tailscale/tailscale.git
synced 2024-12-04 23:45:34 +00:00
README.md: update how to find tailnet
Signed-off-by: Walter Poupore <walterp@tailscale.com>
This commit is contained in:
parent
6632504f45
commit
25c92913ef
128
api.md
128
api.md
@ -3,11 +3,12 @@
|
|||||||
The Tailscale API is a (mostly) RESTful API. Typically, POST bodies should be JSON encoded and responses will be JSON encoded.
|
The Tailscale API is a (mostly) RESTful API. Typically, POST bodies should be JSON encoded and responses will be JSON encoded.
|
||||||
|
|
||||||
# Authentication
|
# Authentication
|
||||||
|
|
||||||
Currently based on {some authentication method}. Visit the [admin panel](https://login.tailscale.com/admin) and navigate to the `Settings` page. Generate an API Key and keep it safe. Provide the key as the user key in basic auth when making calls to Tailscale API endpoints (leave the password blank).
|
Currently based on {some authentication method}. Visit the [admin panel](https://login.tailscale.com/admin) and navigate to the `Settings` page. Generate an API Key and keep it safe. Provide the key as the user key in basic auth when making calls to Tailscale API endpoints (leave the password blank).
|
||||||
|
|
||||||
# APIs
|
# APIs
|
||||||
|
|
||||||
* **[Devices](#device)**
|
- **[Devices](#device)**
|
||||||
- [GET device](#device-get)
|
- [GET device](#device-get)
|
||||||
- [DELETE device](#device-delete)
|
- [DELETE device](#device-delete)
|
||||||
- Routes
|
- Routes
|
||||||
@ -19,7 +20,7 @@ Currently based on {some authentication method}. Visit the [admin panel](https:/
|
|||||||
- [POST device tags](#device-tags-post)
|
- [POST device tags](#device-tags-post)
|
||||||
- Key
|
- Key
|
||||||
- [POST device key](#device-key-post)
|
- [POST device key](#device-key-post)
|
||||||
* **[Tailnets](#tailnet)**
|
- **[Tailnets](#tailnet)**
|
||||||
- ACLs
|
- ACLs
|
||||||
- [GET tailnet ACL](#tailnet-acl-get)
|
- [GET tailnet ACL](#tailnet-acl-get)
|
||||||
- [POST tailnet ACL](#tailnet-acl-post)
|
- [POST tailnet ACL](#tailnet-acl-post)
|
||||||
@ -41,7 +42,9 @@ Currently based on {some authentication method}. Visit the [admin panel](https:/
|
|||||||
- [POST tailnet DNS searchpaths](#tailnet-dns-searchpaths-post)
|
- [POST tailnet DNS searchpaths](#tailnet-dns-searchpaths-post)
|
||||||
|
|
||||||
## Device
|
## Device
|
||||||
|
|
||||||
<!-- TODO: description about what devices are -->
|
<!-- TODO: description about what devices are -->
|
||||||
|
|
||||||
Each Tailscale-connected device has a globally-unique identifier number which we refer as the "deviceID" or sometimes, just "id".
|
Each Tailscale-connected device has a globally-unique identifier number which we refer as the "deviceID" or sometimes, just "id".
|
||||||
You can use the deviceID to specify operations on a specific device, like retrieving its subnet routes.
|
You can use the deviceID to specify operations on a specific device, like retrieving its subnet routes.
|
||||||
|
|
||||||
@ -52,20 +55,23 @@ This is your deviceID.
|
|||||||
<a name=device-get></a>
|
<a name=device-get></a>
|
||||||
|
|
||||||
#### `GET /api/v2/device/:deviceid` - lists the details for a device
|
#### `GET /api/v2/device/:deviceid` - lists the details for a device
|
||||||
|
|
||||||
Returns the details for the specified device.
|
Returns the details for the specified device.
|
||||||
Supply the device of interest in the path using its ID.
|
Supply the device of interest in the path using its ID.
|
||||||
Use the `fields` query parameter to explicitly indicate which fields are returned.
|
Use the `fields` query parameter to explicitly indicate which fields are returned.
|
||||||
|
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
##### Query Parameters
|
##### Query Parameters
|
||||||
|
|
||||||
`fields` - Controls which fields will be included in the returned response.
|
`fields` - Controls which fields will be included in the returned response.
|
||||||
Currently, supported options are:
|
Currently, supported options are:
|
||||||
* `all`: returns all fields in the response.
|
|
||||||
* `default`: return all fields except:
|
- `all`: returns all fields in the response.
|
||||||
* `enabledRoutes`
|
- `default`: return all fields except:
|
||||||
* `advertisedRoutes`
|
- `enabledRoutes`
|
||||||
* `clientConnectivity` (which contains the following fields: `mappingVariesByDestIP`, `derp`, `endpoints`, `latency`, and `clientSupports`)
|
- `advertisedRoutes`
|
||||||
|
- `clientConnectivity` (which contains the following fields: `mappingVariesByDestIP`, `derp`, `endpoints`, `latency`, and `clientSupports`)
|
||||||
|
|
||||||
Use commas to separate multiple options.
|
Use commas to separate multiple options.
|
||||||
If more than one option is indicated, then the union is used.
|
If more than one option is indicated, then the union is used.
|
||||||
@ -73,6 +79,7 @@ For example, for `fields=default,all`, all fields are returned.
|
|||||||
If the `fields` parameter is not provided, then the default option is used.
|
If the `fields` parameter is not provided, then the default option is used.
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
```
|
```
|
||||||
GET /api/v2/device/12345
|
GET /api/v2/device/12345
|
||||||
curl 'https://api.tailscale.com/api/v2/device/12345?fields=all' \
|
curl 'https://api.tailscale.com/api/v2/device/12345?fields=all' \
|
||||||
@ -80,6 +87,7 @@ curl 'https://api.tailscale.com/api/v2/device/12345?fields=all' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response
|
Response
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"addresses":[
|
"addresses":[
|
||||||
@ -141,16 +149,18 @@ Response
|
|||||||
<a name=device-delete></a>
|
<a name=device-delete></a>
|
||||||
|
|
||||||
#### `DELETE /api/v2/device/:deviceID` - deletes the device from its tailnet
|
#### `DELETE /api/v2/device/:deviceID` - deletes the device from its tailnet
|
||||||
|
|
||||||
Deletes the provided device from its tailnet.
|
Deletes the provided device from its tailnet.
|
||||||
The device must belong to the user's tailnet.
|
The device must belong to the user's tailnet.
|
||||||
Deleting shared/external devices is not supported.
|
Deleting shared/external devices is not supported.
|
||||||
Supply the device of interest in the path using its ID.
|
Supply the device of interest in the path using its ID.
|
||||||
|
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
No parameters.
|
No parameters.
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
```
|
```
|
||||||
DELETE /api/v2/device/12345
|
DELETE /api/v2/device/12345
|
||||||
curl -X DELETE 'https://api.tailscale.com/api/v2/device/12345' \
|
curl -X DELETE 'https://api.tailscale.com/api/v2/device/12345' \
|
||||||
@ -160,6 +170,7 @@ curl -X DELETE 'https://api.tailscale.com/api/v2/device/12345' \
|
|||||||
Response
|
Response
|
||||||
|
|
||||||
If successful, the response should be empty:
|
If successful, the response should be empty:
|
||||||
|
|
||||||
```
|
```
|
||||||
< HTTP/1.1 200 OK
|
< HTTP/1.1 200 OK
|
||||||
...
|
...
|
||||||
@ -168,13 +179,13 @@ If successful, the response should be empty:
|
|||||||
```
|
```
|
||||||
|
|
||||||
If the device is not owned by your tailnet:
|
If the device is not owned by your tailnet:
|
||||||
|
|
||||||
```
|
```
|
||||||
< HTTP/1.1 501 Not Implemented
|
< HTTP/1.1 501 Not Implemented
|
||||||
...
|
...
|
||||||
{"message":"cannot delete devices outside of your tailnet"}
|
{"message":"cannot delete devices outside of your tailnet"}
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
<a name=device-routes-get></a>
|
<a name=device-routes-get></a>
|
||||||
|
|
||||||
#### `GET /api/v2/device/:deviceID/routes` - fetch subnet routes that are advertised and enabled for a device
|
#### `GET /api/v2/device/:deviceID/routes` - fetch subnet routes that are advertised and enabled for a device
|
||||||
@ -193,6 +204,7 @@ curl 'https://api.tailscale.com/api/v2/device/11055/routes' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response
|
Response
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"advertisedRoutes" : [
|
"advertisedRoutes" : [
|
||||||
@ -213,7 +225,9 @@ Sets which subnet routes are enabled to be routed by a device by replacing the e
|
|||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### POST Body
|
###### POST Body
|
||||||
|
|
||||||
`routes` - The new list of enabled subnet routes in JSON.
|
`routes` - The new list of enabled subnet routes in JSON.
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"routes": ["10.0.1.0/24", "1.2.0.0/16", "2.0.0.0/24"]
|
"routes": ["10.0.1.0/24", "1.2.0.0/16", "2.0.0.0/24"]
|
||||||
@ -254,7 +268,9 @@ Marks a device as authorized, for Tailnets where device authorization is require
|
|||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### POST Body
|
###### POST Body
|
||||||
|
|
||||||
`authorized` - whether the device is authorized; only `true` is currently supported.
|
`authorized` - whether the device is authorized; only `true` is currently supported.
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"authorized": true
|
"authorized": true
|
||||||
@ -335,9 +351,9 @@ The response is 2xx on success. The response body is currently an empty JSON
|
|||||||
object.
|
object.
|
||||||
|
|
||||||
## Tailnet
|
## Tailnet
|
||||||
A tailnet is the name of your Tailscale network.
|
|
||||||
You can find it in the top left corner of the [Admin Panel](https://login.tailscale.com/admin) beside the Tailscale logo.
|
|
||||||
|
|
||||||
|
A tailnet is the name of your Tailscale network.
|
||||||
|
You can find it in the [Settings](https://login.tailscale.com/admin/settings/) page of the admin console.
|
||||||
|
|
||||||
`alice@example.com` belongs to the `example.com` tailnet and would use the following format for API calls:
|
`alice@example.com` belongs to the `example.com` tailnet and would use the following format for API calls:
|
||||||
|
|
||||||
@ -346,10 +362,10 @@ GET /api/v2/tailnet/example.com/...
|
|||||||
curl https://api.tailscale.com/api/v2/tailnet/example.com/...
|
curl https://api.tailscale.com/api/v2/tailnet/example.com/...
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
For solo plans, the tailnet is the email you signed up with.
|
For solo plans, the tailnet is the email you signed up with.
|
||||||
So `alice@gmail.com` has the tailnet `alice@gmail.com` since `@gmail.com` is a shared email host.
|
So `alice@gmail.com` has the tailnet `alice@gmail.com` since `@gmail.com` is a shared email host.
|
||||||
Her API calls would have the following format:
|
Her API calls would have the following format:
|
||||||
|
|
||||||
```
|
```
|
||||||
GET /api/v2/tailnet/alice@gmail.com/...
|
GET /api/v2/tailnet/alice@gmail.com/...
|
||||||
curl https://api.tailscale.com/api/v2/tailnet/alice@gmail.com/...
|
curl https://api.tailscale.com/api/v2/tailnet/alice@gmail.com/...
|
||||||
@ -370,15 +386,19 @@ Retrieves the ACL that is currently set for the given tailnet. Supply the tailne
|
|||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### Headers
|
###### Headers
|
||||||
|
|
||||||
`Accept` - Response is parsed `JSON` if `application/json` is explicitly named, otherwise HuJSON will be returned.
|
`Accept` - Response is parsed `JSON` if `application/json` is explicitly named, otherwise HuJSON will be returned.
|
||||||
|
|
||||||
##### Returns
|
##### Returns
|
||||||
|
|
||||||
Returns the ACL HuJSON by default. Returns a parsed JSON of the ACL (sans comments) if the `Accept` type is explicitly set to `application/json`. An `ETag` header is also sent in the response, which can be optionally used in POST requests to avoid missed updates.
|
Returns the ACL HuJSON by default. Returns a parsed JSON of the ACL (sans comments) if the `Accept` type is explicitly set to `application/json`. An `ETag` header is also sent in the response, which can be optionally used in POST requests to avoid missed updates.
|
||||||
|
|
||||||
<!-- TODO (chungdaniel): define error types and a set of docs for them -->
|
<!-- TODO (chungdaniel): define error types and a set of docs for them -->
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
###### Requesting a HuJSON response:
|
###### Requesting a HuJSON response:
|
||||||
|
|
||||||
```
|
```
|
||||||
GET /api/v2/tailnet/example.com/acl
|
GET /api/v2/tailnet/example.com/acl
|
||||||
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
|
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
|
||||||
@ -388,6 +408,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response
|
Response
|
||||||
|
|
||||||
```
|
```
|
||||||
...
|
...
|
||||||
Content-Type: application/hujson
|
Content-Type: application/hujson
|
||||||
@ -426,6 +447,7 @@ Etag: "e0b2816b418b3f266309d94426ac7668ab3c1fa87798785bf82f1085cc2f6d9c"
|
|||||||
```
|
```
|
||||||
|
|
||||||
###### Requesting a JSON response:
|
###### Requesting a JSON response:
|
||||||
|
|
||||||
```
|
```
|
||||||
GET /api/v2/tailnet/example.com/acl
|
GET /api/v2/tailnet/example.com/acl
|
||||||
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
|
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
|
||||||
@ -435,6 +457,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response
|
Response
|
||||||
|
|
||||||
```
|
```
|
||||||
...
|
...
|
||||||
Content-Type: application/json
|
Content-Type: application/json
|
||||||
@ -477,6 +500,7 @@ Returns the updated ACL in JSON or HuJSON according to the `Accept` header on su
|
|||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### Headers
|
###### Headers
|
||||||
|
|
||||||
`If-Match` - A request header. Set this value to the ETag header provided in an `ACL GET` request to avoid missed updates.
|
`If-Match` - A request header. Set this value to the ETag header provided in an `ACL GET` request to avoid missed updates.
|
||||||
|
|
||||||
`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.
|
||||||
@ -486,15 +510,16 @@ Returns the updated ACL in JSON or HuJSON according to the `Accept` header on su
|
|||||||
The POST body should be a JSON or [HuJSON](https://github.com/tailscale/hujson#hujson---human-json) formatted JSON object.
|
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:
|
An ACL policy may contain the following top-level properties:
|
||||||
|
|
||||||
* `Groups` - Static groups of users which can be used for ACL rules.
|
- `Groups` - Static groups of users which can be used for ACL rules.
|
||||||
* `Hosts` - Hostname aliases to use in place of IP addresses or subnets.
|
- `Hosts` - Hostname aliases to use in place of IP addresses or subnets.
|
||||||
* `ACLs` - Access control lists.
|
- `ACLs` - Access control lists.
|
||||||
* `TagOwners` - Defines who is allowed to use which tags.
|
- `TagOwners` - Defines who is allowed to use which tags.
|
||||||
* `Tests` - Run on ACL updates to check correct functionality of defined ACLs.
|
- `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.
|
See https://tailscale.com/kb/1018/acls for more information on those properties.
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /api/v2/tailnet/example.com/acl
|
POST /api/v2/tailnet/example.com/acl
|
||||||
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
|
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl' \
|
||||||
@ -524,6 +549,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.
|
||||||
{
|
{
|
||||||
@ -549,6 +575,7 @@ Response:
|
|||||||
```
|
```
|
||||||
|
|
||||||
Failed test error response:
|
Failed test error response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"message": "test(s) failed",
|
"message": "test(s) failed",
|
||||||
@ -572,14 +599,17 @@ Determines what rules match for a user on an ACL without saving the ACL to the s
|
|||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### Query Parameters
|
###### Query Parameters
|
||||||
|
|
||||||
`type` - can be 'user' or 'ipport'
|
`type` - can be 'user' or 'ipport'
|
||||||
`previewFor` - if type=user, a user's email. If type=ipport, a IP address + port like "10.0.0.1:80".
|
`previewFor` - if type=user, a user's email. If type=ipport, a IP address + port like "10.0.0.1:80".
|
||||||
The provided ACL is queried with this parameter to determine which rules match.
|
The provided ACL is queried with this parameter to determine which rules match.
|
||||||
|
|
||||||
###### POST Body
|
###### POST Body
|
||||||
|
|
||||||
ACL JSON or HuJSON (see https://tailscale.com/kb/1018/acls)
|
ACL JSON or HuJSON (see https://tailscale.com/kb/1018/acls)
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
```
|
```
|
||||||
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/preview?previewFor=user1@example.com&type=user' \
|
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/preview?previewFor=user1@example.com&type=user' \
|
||||||
-u "tskey-yourapikey123:" \
|
-u "tskey-yourapikey123:" \
|
||||||
@ -607,6 +637,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/preview?previewFo
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{"matches":[{"users":["*"],"ports":["*:*"],"lineNumber":19}],"user":"user1@example.com"}
|
{"matches":[{"users":["*"],"ports":["*:*"],"lineNumber":19}],"user":"user1@example.com"}
|
||||||
```
|
```
|
||||||
@ -631,6 +662,7 @@ The POST body should be a JSON formatted array of ACL Tests.
|
|||||||
See https://tailscale.com/kb/1018/acls for more information on the format of ACL tests.
|
See https://tailscale.com/kb/1018/acls for more information on the format of ACL tests.
|
||||||
|
|
||||||
##### Example with tests
|
##### Example with tests
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /api/v2/tailnet/example.com/acl/validate
|
POST /api/v2/tailnet/example.com/acl/validate
|
||||||
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/validate' \
|
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/validate' \
|
||||||
@ -642,6 +674,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/validate' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
##### Example with an ACL body
|
##### Example with an ACL body
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /api/v2/tailnet/example.com/acl/validate
|
POST /api/v2/tailnet/example.com/acl/validate
|
||||||
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/validate' \
|
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/acl/validate' \
|
||||||
@ -684,21 +717,23 @@ An empty body or a JSON object with no `message` is returned on success.
|
|||||||
<a name=tailnet-devices-get></a>
|
<a name=tailnet-devices-get></a>
|
||||||
|
|
||||||
#### <a name="getdevices"></a> `GET /api/v2/tailnet/:tailnet/devices` - list the devices for a tailnet
|
#### <a name="getdevices"></a> `GET /api/v2/tailnet/:tailnet/devices` - list the devices for a tailnet
|
||||||
|
|
||||||
Lists the devices in a tailnet.
|
Lists the devices in a tailnet.
|
||||||
Supply the tailnet of interest in the path.
|
Supply the tailnet of interest in the path.
|
||||||
Use the `fields` query parameter to explicitly indicate which fields are returned.
|
Use the `fields` query parameter to explicitly indicate which fields are returned.
|
||||||
|
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### Query Parameters
|
###### Query Parameters
|
||||||
|
|
||||||
`fields` - Controls which fields will be included in the returned response.
|
`fields` - Controls which fields will be included in the returned response.
|
||||||
Currently, supported options are:
|
Currently, supported options are:
|
||||||
* `all`: Returns all fields in the response.
|
|
||||||
* `default`: return all fields except:
|
- `all`: Returns all fields in the response.
|
||||||
* `enabledRoutes`
|
- `default`: return all fields except:
|
||||||
* `advertisedRoutes`
|
- `enabledRoutes`
|
||||||
* `clientConnectivity` (which contains the following fields: `mappingVariesByDestIP`, `derp`, `endpoints`, `latency`, and `clientSupports`)
|
- `advertisedRoutes`
|
||||||
|
- `clientConnectivity` (which contains the following fields: `mappingVariesByDestIP`, `derp`, `endpoints`, `latency`, and `clientSupports`)
|
||||||
|
|
||||||
Use commas to separate multiple options.
|
Use commas to separate multiple options.
|
||||||
If more than one option is indicated, then the union is used.
|
If more than one option is indicated, then the union is used.
|
||||||
@ -714,6 +749,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/devices' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response
|
Response
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"devices":[
|
"devices":[
|
||||||
@ -776,6 +812,7 @@ for the user who owns the API key used to perform this query.
|
|||||||
Supply the tailnet of interest in the path.
|
Supply the tailnet of interest in the path.
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
No parameters.
|
No parameters.
|
||||||
|
|
||||||
##### Returns
|
##### Returns
|
||||||
@ -792,6 +829,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/keys' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{"keys": [
|
{"keys": [
|
||||||
{"id": "kYKVU14CNTRL"},
|
{"id": "kYKVU14CNTRL"},
|
||||||
@ -812,7 +850,9 @@ Supply the tailnet in the path.
|
|||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### POST Body
|
###### POST Body
|
||||||
|
|
||||||
`capabilities` - A mapping of resources to permissible actions.
|
`capabilities` - A mapping of resources to permissible actions.
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"capabilities": {
|
"capabilities": {
|
||||||
@ -859,6 +899,7 @@ echo '{
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"id": "k123456CNTRL",
|
"id": "k123456CNTRL",
|
||||||
@ -877,6 +918,7 @@ Returns a JSON object with information about specific key.
|
|||||||
Supply the tailnet and key ID of interest in the path.
|
Supply the tailnet and key ID of interest in the path.
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
No parameters.
|
No parameters.
|
||||||
|
|
||||||
##### Returns
|
##### Returns
|
||||||
@ -893,6 +935,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/keys/k123456CNTRL' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"id": "k123456CNTRL",
|
"id": "k123456CNTRL",
|
||||||
@ -922,9 +965,11 @@ Deletes a specific key.
|
|||||||
Supply the tailnet and key ID of interest in the path.
|
Supply the tailnet and key ID of interest in the path.
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
No parameters.
|
No parameters.
|
||||||
|
|
||||||
##### Returns
|
##### Returns
|
||||||
|
|
||||||
This reports status 200 upon success.
|
This reports status 200 upon success.
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
@ -941,10 +986,12 @@ curl -X DELETE 'https://api.tailscale.com/api/v2/tailnet/example.com/keys/k12345
|
|||||||
<a name=tailnet-dns-nameservers-get></a>
|
<a name=tailnet-dns-nameservers-get></a>
|
||||||
|
|
||||||
#### `GET /api/v2/tailnet/:tailnet/dns/nameservers` - list the DNS nameservers for a tailnet
|
#### `GET /api/v2/tailnet/:tailnet/dns/nameservers` - list the DNS nameservers for a tailnet
|
||||||
|
|
||||||
Lists the DNS nameservers for a tailnet.
|
Lists the DNS nameservers for a tailnet.
|
||||||
Supply the tailnet of interest in the path.
|
Supply the tailnet of interest in the path.
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
No parameters.
|
No parameters.
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
@ -956,6 +1003,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/nameservers' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response
|
Response
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"dns": ["8.8.8.8"],
|
"dns": ["8.8.8.8"],
|
||||||
@ -965,13 +1013,17 @@ Response
|
|||||||
<a name=tailnet-dns-nameservers-post></a>
|
<a name=tailnet-dns-nameservers-post></a>
|
||||||
|
|
||||||
#### `POST /api/v2/tailnet/:tailnet/dns/nameservers` - replaces the list of DNS nameservers for a tailnet
|
#### `POST /api/v2/tailnet/:tailnet/dns/nameservers` - replaces the list of DNS nameservers for a tailnet
|
||||||
|
|
||||||
Replaces the list of DNS nameservers for the given tailnet with the list supplied by the user.
|
Replaces the list of DNS nameservers for the given tailnet with the list supplied by the user.
|
||||||
Supply the tailnet of interest in the path.
|
Supply the tailnet of interest in the path.
|
||||||
Note that changing the list of DNS nameservers may also affect the status of MagicDNS (if MagicDNS is on).
|
Note that changing the list of DNS nameservers may also affect the status of MagicDNS (if MagicDNS is on).
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### POST Body
|
###### POST Body
|
||||||
|
|
||||||
`dns` - The new list of DNS nameservers in JSON.
|
`dns` - The new list of DNS nameservers in JSON.
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"dns":["8.8.8.8"]
|
"dns":["8.8.8.8"]
|
||||||
@ -979,12 +1031,15 @@ Note that changing the list of DNS nameservers may also affect the status of Mag
|
|||||||
```
|
```
|
||||||
|
|
||||||
##### Returns
|
##### Returns
|
||||||
|
|
||||||
Returns the new list of nameservers and the status of MagicDNS.
|
Returns the new list of nameservers and the status of MagicDNS.
|
||||||
|
|
||||||
If all nameservers have been removed, MagicDNS will be automatically disabled (until explicitly turned back on by the user).
|
If all nameservers have been removed, MagicDNS will be automatically disabled (until explicitly turned back on by the user).
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
###### Adding DNS nameservers with the MagicDNS on:
|
###### Adding DNS nameservers with the MagicDNS on:
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /api/v2/tailnet/example.com/dns/nameservers
|
POST /api/v2/tailnet/example.com/dns/nameservers
|
||||||
curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/nameservers' \
|
curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/nameservers' \
|
||||||
@ -993,6 +1048,7 @@ curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/nameserve
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"dns":["8.8.8.8"],
|
"dns":["8.8.8.8"],
|
||||||
@ -1001,6 +1057,7 @@ Response:
|
|||||||
```
|
```
|
||||||
|
|
||||||
###### Removing all DNS nameservers with the MagicDNS on:
|
###### Removing all DNS nameservers with the MagicDNS on:
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /api/v2/tailnet/example.com/dns/nameservers
|
POST /api/v2/tailnet/example.com/dns/nameservers
|
||||||
curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/nameservers' \
|
curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/nameservers' \
|
||||||
@ -1009,6 +1066,7 @@ curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/nameserve
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"dns":[],
|
"dns":[],
|
||||||
@ -1019,13 +1077,16 @@ Response:
|
|||||||
<a name=tailnet-dns-preferences-get></a>
|
<a name=tailnet-dns-preferences-get></a>
|
||||||
|
|
||||||
#### `GET /api/v2/tailnet/:tailnet/dns/preferences` - retrieves the DNS preferences for a tailnet
|
#### `GET /api/v2/tailnet/:tailnet/dns/preferences` - retrieves the DNS preferences for a tailnet
|
||||||
|
|
||||||
Retrieves the DNS preferences that are currently set for the given tailnet.
|
Retrieves the DNS preferences that are currently set for the given tailnet.
|
||||||
Supply the tailnet of interest in the path.
|
Supply the tailnet of interest in the path.
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
No parameters.
|
No parameters.
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
```
|
```
|
||||||
GET /api/v2/tailnet/example.com/dns/preferences
|
GET /api/v2/tailnet/example.com/dns/preferences
|
||||||
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/preferences' \
|
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/preferences' \
|
||||||
@ -1033,6 +1094,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/preferences' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"magicDNS":false,
|
"magicDNS":false,
|
||||||
@ -1042,6 +1104,7 @@ Response:
|
|||||||
<a name=tailnet-dns-preferences-post></a>
|
<a name=tailnet-dns-preferences-post></a>
|
||||||
|
|
||||||
#### `POST /api/v2/tailnet/:tailnet/dns/preferences` - replaces the DNS preferences for a tailnet
|
#### `POST /api/v2/tailnet/:tailnet/dns/preferences` - replaces the DNS preferences for a tailnet
|
||||||
|
|
||||||
Replaces the DNS preferences for a tailnet, specifically, the MagicDNS setting.
|
Replaces the DNS preferences for a tailnet, specifically, the MagicDNS setting.
|
||||||
Note that MagicDNS is dependent on DNS servers.
|
Note that MagicDNS is dependent on DNS servers.
|
||||||
|
|
||||||
@ -1051,9 +1114,12 @@ Note that removing all nameservers will turn off MagicDNS.
|
|||||||
To reenable it, nameservers must be added back, and MagicDNS must be explicitly turned on.
|
To reenable it, nameservers must be added back, and MagicDNS must be explicitly turned on.
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### POST Body
|
###### POST Body
|
||||||
|
|
||||||
The DNS preferences in JSON. Currently, MagicDNS is the only setting available.
|
The DNS preferences in JSON. Currently, MagicDNS is the only setting available.
|
||||||
`magicDNS` - Automatically registers DNS names for devices in your tailnet.
|
`magicDNS` - Automatically registers DNS names for devices in your tailnet.
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"magicDNS": true
|
"magicDNS": true
|
||||||
@ -1061,6 +1127,7 @@ The DNS preferences in JSON. Currently, MagicDNS is the only setting available.
|
|||||||
```
|
```
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /api/v2/tailnet/example.com/dns/preferences
|
POST /api/v2/tailnet/example.com/dns/preferences
|
||||||
curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/preferences' \
|
curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/preferences' \
|
||||||
@ -1068,10 +1135,10 @@ curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/preferenc
|
|||||||
--data-binary '{"magicDNS": true}'
|
--data-binary '{"magicDNS": true}'
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
If there are no DNS servers, it returns an error message:
|
If there are no DNS servers, it returns an error message:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"message":"need at least one nameserver to enable MagicDNS"
|
"message":"need at least one nameserver to enable MagicDNS"
|
||||||
@ -1079,6 +1146,7 @@ If there are no DNS servers, it returns an error message:
|
|||||||
```
|
```
|
||||||
|
|
||||||
If there are DNS servers:
|
If there are DNS servers:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"magicDNS":true,
|
"magicDNS":true,
|
||||||
@ -1088,14 +1156,16 @@ If there are DNS servers:
|
|||||||
<a name=tailnet-dns-searchpaths-get></a>
|
<a name=tailnet-dns-searchpaths-get></a>
|
||||||
|
|
||||||
#### `GET /api/v2/tailnet/:tailnet/dns/searchpaths` - retrieves the search paths for a tailnet
|
#### `GET /api/v2/tailnet/:tailnet/dns/searchpaths` - retrieves the search paths for a tailnet
|
||||||
|
|
||||||
Retrieves the list of search paths that is currently set for the given tailnet.
|
Retrieves the list of search paths that is currently set for the given tailnet.
|
||||||
Supply the tailnet of interest in the path.
|
Supply the tailnet of interest in the path.
|
||||||
|
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
No parameters.
|
No parameters.
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
```
|
```
|
||||||
GET /api/v2/tailnet/example.com/dns/searchpaths
|
GET /api/v2/tailnet/example.com/dns/searchpaths
|
||||||
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/searchpaths' \
|
curl 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/searchpaths' \
|
||||||
@ -1103,6 +1173,7 @@ curl 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/searchpaths' \
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"searchPaths": ["user1.example.com"],
|
"searchPaths": ["user1.example.com"],
|
||||||
@ -1112,12 +1183,15 @@ Response:
|
|||||||
<a name=tailnet-dns-searchpaths-post></a>
|
<a name=tailnet-dns-searchpaths-post></a>
|
||||||
|
|
||||||
#### `POST /api/v2/tailnet/:tailnet/dns/searchpaths` - replaces the search paths for a tailnet
|
#### `POST /api/v2/tailnet/:tailnet/dns/searchpaths` - replaces the search paths for a tailnet
|
||||||
|
|
||||||
Replaces the list of searchpaths with the list supplied by the user and returns an error otherwise.
|
Replaces the list of searchpaths with the list supplied by the user and returns an error otherwise.
|
||||||
|
|
||||||
##### Parameters
|
##### Parameters
|
||||||
|
|
||||||
###### POST Body
|
###### POST Body
|
||||||
|
|
||||||
`searchPaths` - A list of searchpaths in JSON.
|
`searchPaths` - A list of searchpaths in JSON.
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"searchPaths": ["user1.example.com", "user2.example.com"]
|
"searchPaths": ["user1.example.com", "user2.example.com"]
|
||||||
@ -1125,6 +1199,7 @@ Replaces the list of searchpaths with the list supplied by the user and returns
|
|||||||
```
|
```
|
||||||
|
|
||||||
##### Example
|
##### Example
|
||||||
|
|
||||||
```
|
```
|
||||||
POST /api/v2/tailnet/example.com/dns/searchpaths
|
POST /api/v2/tailnet/example.com/dns/searchpaths
|
||||||
curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/searchpaths' \
|
curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/searchpaths' \
|
||||||
@ -1133,6 +1208,7 @@ curl -X POST 'https://api.tailscale.com/api/v2/tailnet/example.com/dns/searchpat
|
|||||||
```
|
```
|
||||||
|
|
||||||
Response:
|
Response:
|
||||||
|
|
||||||
```
|
```
|
||||||
{
|
{
|
||||||
"searchPaths": ["user1.example.com", "user2.example.com"],
|
"searchPaths": ["user1.example.com", "user2.example.com"],
|
||||||
|
Loading…
Reference in New Issue
Block a user