TheArchive/tailscale
1
0
Fork 0
mirror of https://github.com/tailscale/tailscale.git synced 2024-12-04 15:35:38 +00:00
Code Issues Packages Projects Releases Wiki Activity

README.md: update how to find tailnet

Browse Source 
Signed-off-by: Walter Poupore <walterp@tailscale.com>
This commit is contained in:
Walter Poupore 2022-09-19 17:06:44 -07:00
parent 6632504f45
commit 25c92913ef
1 changed files with 104 additions and 28 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

132
api.md
View File

@ -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,12 +20,12 @@ 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)
- [POST tailnet ACL preview](#tailnet-acl-preview-post) - [POST tailnet ACL preview](#tailnet-acl-preview-post)
- [POST tailnet ACL validate](#tailnet-acl-validate-post) - [POST tailnet ACL validate](#tailnet-acl-validate-post)
- [Devices](#tailnet-devices) - [Devices](#tailnet-devices)
- [GET tailnet devices](#tailnet-devices-get) - [GET tailnet devices](#tailnet-devices-get)
- [Keys](#tailnet-keys) - [Keys](#tailnet-keys)
@ -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"],