Tailscale daemon configuration file

The tailscaled configuration file support is in alpha and the schema might change in future releases. Tailscale intends to preserve compatibility with earlier versions when possible. If breaking changes occur, a new version designation will be used.

You can configure the Tailscale daemon (tailscaled) using a JSON configuration file instead of command-line flags passed to the Tailscale CLI. This approach is useful for headless deployments, containers, Kubernetes, and infrastructure-as-code workflows.

Basic usage

The tailscaled configuration file only requires you to set the version field manually. The following example shows a minimal configuration example:

{
  "version": "alpha0",
  "authKey": "tskey-auth-example-XXXXX",
  "hostname": "my-server",
  "acceptRoutes": true
}

To start tailscaled with a configuration file, use the --config flag:

tailscaled --config=/etc/tailscale/config.json

The Tailscale daemon does not automatically discover configuration files. You must specify the path explicitly using the --config flag.

Configuration options

The configuration file uses JSON or HuJSON format. The following tables describe all available options. This section organizes all configuration options by category.

Required options

The version field is the only required option because all other necessary options have default values. If you omit optional fields, the Tailscale daemon uses the default values.

Option	Type	Description
`version`	String	Required. The version of the configuration file schema. The only supported value is `"alpha0"`.

Authentication

The following configuration options are for authenticating with the Tailscale control plane.

Option	Type	Default	Description
`serverURL`	String	`https://controlplane.tailscale.com`	Specify the URL of a custom control server.
`authKey`	String	None	Specify an Auth key or OAuth client secret for authentication. Prefix with `file:` to read from a file path (for example, `file:/etc/tailscale/authkey`). The daemon re-reads the file each time it authenticates with the control plane.

General settings

The following configuration options are options for general Tailscale behavior.

Option	Type	Default	Description
`locked`	Boolean	`true`	Set to `true` to prevent configuration changes by using the `tailscale set` command, ensuring the configuration stays consistent with the file. Set to `false` to allow runtime modifications.
`enabled`	Boolean	`true`	Specify whether Tailscale should be running. Setting this to `false` has the same effect as running `tailscale down`.
`hostname`	String	OS hostname	Specify the hostname for the device as displayed in the admin console and used for MagicDNS.
`operatorUser`	String	None	Specify a local Unix username allowed to operate `tailscaled` without root privileges.

DNS and routing

The following configuration options are options for DNS and subnet routing.

Option	Type	Default	Description
`acceptDNS`	Boolean	`true`	Set to `false` to disable using the DNS configuration from the tailnet.
`acceptRoutes`	Boolean	Platform-dependent	Set to `true` to accept subnet routes advertised by other devices.
`advertiseRoutes`	Array of Strings	None	An array of subnet routes to advertise to the tailnet. Use the format `["<CIDR>"]`.
`disableSNAT`	Boolean	`false`	Set to `true` to disable source NAT for traffic to advertised subnet routes.

Platform-dependent default values for acceptRoutes:

Defaults to true for Windows, iOS, Android, the macOS App Store variant, and the macOS Standalone variant.
Defaults to false Unix platforms (Linux, BSD, and the macOS open source variant).

Exit nodes

The following configuration options are options for exit nodes.

Option	Type	Default	Description
`exitNode`	String	None	Exit node to use. You can use an IP address, stable node ID, or MagicDNS base name. It accepts any value supported by the `tailscale set --exit-node=<identifier>` command.
`allowLANWhileUsingExitNode`	Boolean	`false`	Set to `true` to permit access to the local network (LAN) while routing traffic through an exit node.

You can find the stable node ID of a device in the Machines of the admin console.

Features

The following configuration options are for enabling or disabling specific Tailscale features.

Option	Type	Default	Description
`runSSHServer`	Boolean	`false`	Set to `true` to enable Tailscale SSH server.
`runWebClient`	Boolean	`false`	Set to `true` to enable the Tailscale web client interface.
`shieldsUp`	Boolean	`false`	Set to `true` to block all incoming connections from other tailnet regardless of access control policies. You might consider this if you only want to permit outbound connections. This is similar to how you can configure incoming connections in the Tailscale client.
`postureChecking`	Boolean	`false`	Set to `true` to enable device posture data collection.
`advertiseServices`	Array of Strings	None	Specify services to advertise (for example, `["svc:my-api"]`). Used with Tailscale Service virtual IP addresses for high availability.
`appConnector`	Object	None	App connector configuration. Set `{"advertise": true}` to run as an app connector.

Auto-update

The following configuration options are options for automatic updates.

Option	Type	Default	Description
`autoUpdate`	Object	None	Auto-update preferences. Set to `check` to enable checking for updates. Set to `apply` to automatically apply updates. For example: `{"check": true, "apply": false}`.

Linux-specific options

Linux-specific configuration options.

Option	Type	Default	Description
`netfilterMode`	String	`"on"`	Set the firewall management mode: `"on"`, `"nodivert"`, or `"off"`. This specifies how `tailscaled` manages `iptables`/`nftables` rules on Linux.
`noStatefulFiltering`	Boolean	`false`	Set to `true` to disable stateful packet filtering for subnet routers and exit nodes.

`netfilterMode` values

on: Normal operation. In this mode, tailscaled creates iptables/nftables chains and adds a rule to start of the relevant standard chains that jumps into them. For example, it inserts a jump to ts-input at the start of the filter table INPUT chain, to ts-forward from FORWARD, to ts-output from OUTPUT, and so on. It also adds a ts-postrouting in the nat table.
nodivert: No divert mode. In this mode, tailscaled creates iptables/nftables chains as usual, but does not send traffic to them. For the system to work correctly, you must configure those rules manually (for example, add a jump from INPUT to ts-input). This makes it possible to have other rules take effect before the Tailscale rules. Using nodivert also means that tailscaled won't rewrite the jumps occasionally because this would move the Tailscale rules back to the start.
off: In this mode, tailscaled does not make any changes to iptables/nftables. There usually isn't a good reason to use this mode.

Advanced options

The following configuration options are options for advanced use cases, such as customizing the Kubernetes Operators.

Option	Type	Default	Description
`staticEndpoints`	Array of Strings	None	Specify an array of additional WireGuard endpoints to advertise alongside discovered endpoints. Use the format `["<address>:<port>"]`. Refer to Kubernetes Operator customization for more information.

Schema reference

The following schema shows all available options in a single block. Remove all comments before using this in a JSON file, or use HuJSON format to keep them.

{
  "version": "alpha0", // Required.
  "serverURL": "https://controlplane.tailscale.com", // Optional.
  "authKey": "<auth-key>", // Optional.
  "locked": true, // Optional.
  "enabled": true, // Optional.
  "hostname": "<hostname>", // Optional. Default: OS hostname.
  "operatorUser": "<username>", // Optional.
  "acceptDNS": <true|false>, // Optional. Default: platform-dependent.
  "acceptRoutes": <true|false>, // Optional. Default: platform-dependent.
  "advertiseRoutes": ["<CIDR>"], // Optional.
  "disableSNAT": false, // Optional.
  "exitNode": "<IP-address|stable-node-ID|MagicDNS-name>", // Optional.
  "allowLANWhileUsingExitNode": false, // Optional.
  "runSSHServer": false, // Optional.
  "runWebClient": false, // Optional.
  "shieldsUp": false, // Optional.
  "postureChecking": false, // Optional.
  "advertiseServices": ["svc:<service-name>"], // Optional.
  "appConnector": {"advertise": <true|false>}, // Optional.
  "autoUpdate": {"check": <true|false>, "apply": <true|false>}, // Optional.
  "netfilterMode": "on", // Optional (Linux-specific). Values: "on", "nodivert", "off".
  "noStatefulFiltering": false, // Optional.
  "staticEndpoints": ["<address>:<port>"], // Optional.
}

Read configuration from cloud metadata

Instead of using a configuration file, you can read configuration options directly from cloud instance metadata.

Cloud metadata support is limited to Amazon EC2. Support for Google Cloud Platform (GCP), Azure, and cloud-init is planned for future releases.

To read configuration from an Amazon EC2 instance, store the configuration in the instance's user data and use the special path vm:user-data:

tailscaled --config=vm:user-data

This tells the tailscaled daemon to read the configuration from the EC2 instance metadata service at http://<ip-address>/latest/user-data.

Limitations

You can use configuration files on Linux and other Unix-like systems where you run tailscaled directly. For macOS, refer to tailscaled on macOS. iOS and Android do not support configuration files.