Mostly inconsequential minor fixes for consistency. A couple of changes
to actual JSON examples, but all still very readable, so I think it's
fine.
Updates #cleanup
Signed-off-by: Will Norris <will@tailscale.com>
// mappingVariesByDestIP (boolean) is 'true' if the host's NAT mappings
// vary based on the destination IP.
@ -221,17 +210,16 @@ You can also [list all devices in the tailnet](#list-tailnet-devices) to get the
// server for incoming traffic.
"latency": {
"Dallas": {
"latencyMs":60.463043
"latencyMs":60.463043,
},
"New York City": {
"preferred": true,
"latencyMs":31.323811
"latencyMs":31.323811,
},
},
// clientSupports (JSON object) identifies features supported by the client.
"clientSupports": {
// hairpinning (boolean) is 'true' if your router can route connections
// from endpoints on your LAN back to your LAN using those endpoints’
// globally-mapped IPv4 addresses/ports
@ -256,7 +244,7 @@ You can also [list all devices in the tailnet](#list-tailnet-devices) to get the
// upnp (boolean) is 'true' if UPnP port-mapping service exists
// on your router.
"upnp":false
"upnp":false,
},
},
@ -266,9 +254,7 @@ You can also [list all devices in the tailnet](#list-tailnet-devices) to get the
// A single node can have multiple tags assigned. This value is empty for
// external devices.
// Learn more about tags at https://tailscale.com/kb/1068/.
"tags": [
"tag:golink"
],
"tags": ["tag:golink"],
// tailnetLockError (string) indicates an issue with the tailnet lock
// node-key signature on this device.
@ -287,8 +273,8 @@ You can also [list all devices in the tailnet](#list-tailnet-devices) to get the
// will contain {"disabled": true}.
// Learn more about posture identity at https://tailscale.com/kb/1326/device-identity
"postureIdentity": {
"serialNumbers": ["CP74LFQJXM"]
}
"serialNumbers": ["CP74LFQJXM"],
},
}
```
@ -301,6 +287,7 @@ Learn more about [subnet routers](https://tailscale.com/kb/1019).
A device can act as a subnet router if its subnet routes are both advertised and enabled.
This is a two-step process, but the steps can occur in any order:
- The device that intends to act as a subnet router exposes its routes by **advertising** them.
This is done in the Tailscale command-line interface.
- The tailnet admin must approve the routes by **enabling** them.
@ -311,6 +298,7 @@ If a device has advertised routes, they are not exposed to traffic until they ar
Conversely, if a tailnet admin pre-approves certain routes by enabling them, they are not available for routing until the device in question has advertised them.
The API exposes two methods for dealing with subnet routes:
- Get routes: [`GET /api/v2/device/{deviceID}/routes`](#get-device-routes) to fetch lists of advertised and enabled routes for a device
- Set routes: [`POST /api/v2/device/{deviceID}/routes`](#set-device-routes) to set enabled routes for a device
@ -335,6 +323,7 @@ The ID of the device.
Controls whether the response returns **all** object fields or only a predefined subset of fields.
Currently, there are two supported options:
- **`all`:** return all object fields in the response
- **`default`:** return all object fields **except**:
- `enabledRoutes`
@ -455,6 +444,7 @@ GET /api/v2/device/{deviceID}/routes
```
Retrieve the list of [subnet routes](#subnet-routes) that a device is advertising, as well as those that are enabled for it:
- **Enabled routes:** The subnet routes for this device that have been approved by the tailnet admin.
- **Advertised routes:** The subnets this device intends to expose.
@ -477,11 +467,8 @@ Returns the enabled and advertised subnet routes for a device.
Specify whether the device is authorized. False to deauthorize an authorized device, and true to authorize a new device or to re-authorize a previously deauthorized device.
```jsonc
{
"authorized": true
"authorized": true,
}
```
@ -612,7 +592,7 @@ The new list of tags for the device.
```jsonc
{
"tags": ["tag:foo", "tag:bar"]
"tags": ["tag:foo", "tag:bar"],
}
```
@ -632,7 +612,7 @@ If the tags supplied in the `POST` call do not exist in the tailnet policy file,
```jsonc
{
"message": "requested tags [tag:madeup tag:wrongexample] are invalid or not permitted"
"message": "requested tags [tag:madeup tag:wrongexample] are invalid or not permitted",
}
```
@ -664,7 +644,7 @@ You can then call this method again with `"keyExpiryDisabled": false` to re-enab
```jsonc
{
"keyExpiryDisabled": true
"keyExpiryDisabled": true,
}
```
@ -713,7 +693,7 @@ This endpoint can be used to replace the existing IPv4 address with a specific v
```jsonc
{
"ipv4": "100.80.0.1"
"ipv4": "100.80.0.1",
}
```
@ -796,6 +776,7 @@ Request a detailed description of the tailnet policy file by providing `details=
If using this, do not supply an `Accept` parameter in the header.
The response will contain a JSON object with the fields:
- **tailnet policy file:** a base64-encoded string representation of the huJSON format
- **warnings:** array of strings for syntactically valid but nonsensical entries
- **errors:** an array of strings for parsing failures
@ -1006,7 +987,7 @@ A successful response returns an HTTP status of '200' and the modified tailnet p
// Match absolutely everything. Comment out this section if you want
The HTTP status code will be '200' if the request was well formed and there were no server errors, even in the case of failing tests or an invalid ACL.
Look at the response body to determine whether there was a problem within your ACL or tests:
- If the tests are valid, an empty body or a JSON object with no `message` is returned.
- If there's a problem, the response body will be a JSON object with a non-empty `message` property and optionally additional details in `data`:
@ -1196,9 +1180,9 @@ Look at the response body to determine whether there was a problem within your A
Returns a JSON object with the IDs of all active keys.
```jsonc
{"keys": [
{
"keys": [
{ "id": "XXXX14CNTRL" },
{ "id": "XXXXZ3CNTRL" },
{ "id": "XXXX43CNTRL" },
{"id": "XXXXgj1CNTRL"}
]}
{ "id": "XXXXgj1CNTRL" },
],
}
```
<ahref="tailnet-keys-post"></a>
@ -1408,6 +1398,7 @@ Note the following about required vs. optional values:
- **`devices`:** A `devices` object is required within `capabilities`, but can be an empty JSON object.
- **`tags`:** Whether tags are required or optional depends on the owner of the auth key:
- When creating an auth key _owned by the tailnet_ (using OAuth), it must have tags.
The auth tags specified for that new auth key must exactly match the tags that are on the OAuth client used to create that auth key (or they must be tags that are owned by the tags that are on the OAuth client used to create the auth key).
- When creating an auth key _owned by a user_ (using a user's access token), tags are optional.
@ -1460,11 +1451,11 @@ It holds the capabilities specified in the request and can no longer be retrieve
"reusable": false,
"ephemeral": false,
"preauthorized": false,
"tags": [ "tag:example" ]
}
}
"tags": ["tag:example"],
},
"description": "dev access"
},
},
"description": "dev access",
}
```
@ -1510,14 +1501,11 @@ The response is a JSON object with information about the key supplied.
"reusable": false,
"ephemeral": true,
"preauthorized": false,
"tags": [
"tag:bar",
"tag:foo"
]
}
}
"tags": ["tag:bar", "tag:foo"],
},
"description": "dev access"
},
},
"description": "dev access",
}
```
@ -1529,7 +1517,7 @@ Response for a revoked (deleted) or expired key will have an `invalid` field set
"created": "2022-05-05T18:55:44Z",
"expires": "2022-08-03T18:55:44Z",
"revoked": "2023-04-01T20:50:00Z",
"invalid": true
"invalid": true,
}
```
@ -1627,7 +1615,7 @@ The new list of DNS nameservers in JSON.
```jsonc
{
"dns":["8.8.8.8"]
"dns":["8.8.8.8"],
}
```
@ -1734,7 +1722,7 @@ The DNS preferences in JSON. Currently, MagicDNS is the only setting available:
```jsonc
{
"magicDNS": true
"magicDNS": true,
}
```
@ -1752,7 +1740,7 @@ If there are no DNS servers, this returns an error message:
```jsonc
{
"message":"need at least one nameserver to enable MagicDNS"
"message":"need at least one nameserver to enable MagicDNS",
}
```
@ -1817,7 +1805,7 @@ Specify a list of search paths in a JSON object: