> For the complete documentation index, see [llms.txt](https://docs.tonic.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tonic.ai/app/workspace/workspace-configuration-settings/data-connection-settings/using-a-connection-tunneling-option/connecting-through-tailscale.md). # Connecting through Tailscale [Tailscale](https://tailscale.com/blog/how-tailscale-works) is a managed virtual private network (VPN). It creates a private mesh network called a tailnet. Each device on the Tailscale network receives a stable private IP address, and can communicate directly with other devices on the tailnet, without the need to open ports to the public internet or to configure VPN gateways. Tonic Structural can join your corporate tailnet as a node. It can then reach database servers that are on the same tailnet, even if those servers are in a private network and have no public IP address. ## Overview of the steps to enable the connection To allow Tonic Structural to reach a database through Tailscale, you: 1. [**Allow connections from the tailnet to your database server.**](#allowing-connections-to-the-database-server-from-the-tailnet) 2. [**Add your database server to the tailnet**](#adding-your-database-server-to-the-tailnet) - Install the Tailscale agent on the server, or configure a subnet router. 3. [**Declare an access control list (ACL) tag**](#declaring-an-acl-tag) - Register the tag in the tailnet policy that Structural uses to identify itself. 4. [**Create an OAuth credential**](#creating-an-oauth-credential) - Generate the client secret that Structural uses to authenticate to your tailnet. 5. [**Configure the Structural workspace**](#configuring-a-workspace-to-use-tailscale-tunneling) - Enable the Tailscale tunnel and provide the connection details. ## Allowing connections to the database server from the tailnet Connections from Structural arrive at the server's Tailscale IP address, not the server's actual IP address. You must configure your database server to allow connections from your tailnet's IP address range. By default, the range is `100.64.0.0/10`, although it can be customized. For a PostgreSQL database server, you add an entry for the subnet in `pg_hba.conf`. ## Adding your database server to the tailnet To make your database server reachable through Tailscale, you can either: * Install Tailscale directly on the database server. * Use a subnet router. ### Installing Tailscale directly on the database server If you have shell access to the database server, then this is the simplest approach. 1. Install Tailscale on the server.\ \ For platform-specific instructions, go to [tailscale.com/download](https://tailscale.com/download). 2. If a browser is available: 1. Run `sudo tailscale up`.\ \ This returns a link that looks like:
``` https://login.tailscale.com/a/0123456789abcdef ``` 2. Open the URL in a browser.\ \ Tailscale prompts for authentication and then adds the server to your tailnet. 3. For headless servers where no browser is available, use the `--auth-key` flag instead: 1. To generate an auth key, go to `https://login.tailscale.com/admin/settings/keys` . 2. Click **Generate auth key**, then indicate whether the key is: * A one-off key - single use, for a single server. * A reusable key - for multiple servers. The generated key starts with `tskey-`. 3. After you generate the key, run:
```bash sudo tailscale up --auth-key= ``` 4. Retrieve the server's Tailscale IP address:
```bash tailscale ip -4 ``` 5. Verify that the device appears at `https://login.tailscale.com/admin/machines`. The server now has a stable Tailscale IP address, which is by default in the `100.x.x.x` range. You use the Tailscale IP address as the value of **Server** in the workspace data connection settings. ### Using a subnet router If you cannot install Tailscale on the database server itself, for example because it is a managed database service, you can instead: 1. Install Tailscale on any other machine that is on the same private network as the database server. 2. Configure the machine as a [subnet router](https://tailscale.com/kb/1019/subnets). A subnet router advertises a CIDR range to your tailnet. Other nodes such as Structural can then use regular IP addresses to reach the devices on that subnet. Tailscale does not need to be installed on those devices. To configure a subnet router: 1. Install Tailscale on a machine that can reach the database server. 2. Start Tailscale with the `--advertise-routes` flag, which specifies the subnet that your database is on:
```bash sudo tailscale up --advertise-routes=10.0.1.0/24 ``` 3. Approve the advertised route: 1. Go to `https://login.tailscale.com/admin/machines`**.** 2. Click the machine. 3. Click **Edit route settings**. 4. Enable the route. When you use a subnet router, then in Structural, you set the value of **Server** to the database server's regular private IP address - for example, `10.0.1.50` - instead of a Tailscale IP address. ## Declaring an ACL tag Tailscale uses ACL tags to control the devices that a given credential can authenticate to. Before you create an OAuth credential, you must declare the tag that you intend to use in your tailnet's ACL policy. 1. Go to `https://login.tailscale.com/admin/acls`**.** 2. Edit the policy JSON. 3. If the policy does not already contain a `tagOwners` section, then add the section. 4. Add the tag to `tagOwners`. For example, to create a tag called `tag:tonic`: ```json "tagOwners": { "tag:tonic": ["your-tailscale-email@example.com"], }, ``` 3. Save the policy. ## Creating an OAuth credential Structural authenticates to your tailnet using an OAuth client credential. You create this from the Tailscale admin console under **Trust credentials**. 1. Go to `https://login.tailscale.com/admin/settings/trust-credentials`. 2. Click **+ Credential**. 3. Select **OAuth** as the credential type.

New Tailscale credential with OAuth selected as the credential type

4. Add a description, then click **Next**. 5. To set the credential scope: 1. From the **Scopes** dropdown, select **Custom scopes.** 2. Under **Keys**, for **Auth Keys**, check the **Write** checkbox. 3. In the **Tags** field, provide the ACL tag that you created. 6. Click **Generate credential**.\ \ Tailscale displays the **Credential created** panel with the client ID and the client secret.

Credential created panel with the client ID and client secret for the Tailscale OAuth credential

7. Copy the **Client secret** immediately. It is only shown once.\ \ The client secret starts with `tskey-client-`.\ \ In the Structural workspace configuration, you paste this value into the **Tailscale** **Auth Key** field. Structural does not use the client ID. ## Configuring a workspace to use Tailscale tunneling After you complete the setup in Tailscale, you can configure a Structural workspace to connect through Tailscale. ### Setting the database connection server value When you connect through Tailscale, in the database connection fields, to set the value of **Server**: * If you installed Tailscale on the database server, set **Server** to the Tailscale IP address, which is the stable address that is assigned to the device on your tailnet. By default, the address in the `100.x.x.x` range. * If you use a subnet router, then in Structural, set **Server** to the database server's regular private IP address - for example, `10.0.1.50`. ### Enabling and configuring the Tailscale connection To enable and configure the Tailscale connection: 1. If the connector supports multiple tunneling options: 1. Toggle **Enable Connection Tunnel** to the on position. 2. From the **Tunnel type** dropdown list, select **Tailscale Tunnel**. If the data connector only supports Tailscale tunneling, then it is selected automatically. 2. In the **Tags** field, provide a comma-separated list of ACL tags to use to join the tailnet. For example, `tag:tonic-worker`.\ \ Each tag name must exactly match the tag name that you configured in Tailscale, and must include the `tag:` prefix.\ \ If the tags don't match, then when Structural tries to connect, Tailscale returns an authentication error. 3. Optionally, in the **Control Server URL** field, provide the URL. This is intended for customers who use Headscale or a self-hosted Tailscale control plane. 4. In the **Tailscale Auth Key** field, you can either: * Provide the Tailscale OAuth client credential (value starting with `tskey-client-`) that you generated and copied from Tailscale. Structural does not support other types of Tailscale keys, such as user auth keys. * If secrets managers are available, [select a secret name from a secrets manager](/app/workspace/workspace-configuration-settings/secrets-manager/selecting-a-secrets-manager-secret.md). ## How the connection works When Structural uses Tailscale tunneling to establish a connection: 1. Structural uses the provided credential (OAuth credential or secrets manager secret) to authenticate as a new ephemeral node on your tailnet. 2. The node is tagged with the specified ACL tags. The tags control what the node can reach based on your tailnet policy. 3. Structural uses its Tailscale IP address to connect to the database server. Traffic flows through the encrypted tailnet mesh, not the public internet. 4. When the connection is torn down, the ephemeral node is removed from your tailnet. ## Troubleshooting the connection Here are some errors that might occur during the connection:
ErrorLikely cause
Tailscale authentication failed

Either:

  • The tag in the Tags field does not match the tag on the OAuth credential's auth_keys scope.
  • The tag is not declared in tagOwners in your ACL policy.
Connection times out

Either:

  • The database server is not on the tailnet.
  • The ACL policy does not permit the tagged node to reach it.
Invalid auth key typeYou used a user auth key or a pre-auth key instead of an OAuth client secret.
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.tonic.ai/app/workspace/workspace-configuration-settings/data-connection-settings/using-a-connection-tunneling-option/connecting-through-tailscale.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.