Skip to content

Latest commit

 

History

History
625 lines (447 loc) · 24.9 KB

DOCS.md

File metadata and controls

625 lines (447 loc) · 24.9 KB

Home Assistant Community App: Tailscale

Tailscale is a zero config VPN, which installs on any device in minutes, including your Home Assistant instance.

Create a secure network between your servers, computers, and cloud instances. Even when separated by firewalls or subnets, Tailscale just works. Tailscale manages firewall rules for you, and works from anywhere you are.

Prerequisites

In order to use this app, you'll need a Tailscale account.

It is free to use for personal & hobby projects, up to 100 clients/devices on a single user account. Sign up using your Google, Microsoft or GitHub account at the following URL:

https://tailscale.com/start

You can also create an account during the app installation processes, however, it is nice to know where you need to go later on.

Installation

  1. Click the Home Assistant My button below to open the app on your Home Assistant instance.

    Open this app in your Home Assistant instance.

  2. Click the "Install" button to install the app.

  3. Start the "Tailscale" app.

  4. Check the logs of the "Tailscale" app to see if everything went well.

  5. Open the Web UI of the "Tailscale" app to complete authentication and couple your Home Assistant instance with your Tailscale account. Note: Some browsers don't work with this step. It is recommended to complete this step on a desktop or laptop computer using the Chrome browser.

  6. Check the logs of the "Tailscale" app again, to see if everything went well.

  7. Done!

Configuration

Consider disabling key expiry to avoid losing connection to your Home Assistant device. See Key expiry for more information.

Logging in to Tailscale, you can configure your Tailscale network right from their interface.

https://console.tailscale.com/

Note: Remember to restart the app when the configuration is changed.

Note: This is just an example, not even the default, don't copy and paste it! Create your own!

accept_dns: true
accept_routes: false
advertise_connector: false
advertise_exit_node: false
advertise_routes:                       # the default is [] (an empty list), here are some examples:
  - 192.168.1.0/24
  - fd12:3456:abcd::/64
advertise_tags:                         # the default is [] (an empty list), here are some examples:
  - tag:example
  - tag:homeassistant
always_use_derp: false
exit_node: 100.101.102.103              # this is optional, i.e. it is missing by default
log_suppression: true
log_upload: false
login_server: "https://controlplane.tailscale.com"
share_homeassistant: disabled
share_on_port: 443
services:                               # the default is [] (an empty list), here are some examples:
  - name: svc:audiobookshelf
    target: http://127.0.0.1:13378
    protocol: http
    port: 80
    path: /
snat_subnet_routes: true
stateful_filtering: false
taildrive:
  local_apps: false
  app_configs: false
  backup: false
  config: false
  media: false
  share: false
  ssl: false
taildrop: false
userspace_networking: false

Note

Some of the configuration options are also available on Tailscale's web interface through the Web UI, but they are made read only there. You can't change them through the Web UI, because all the changes made there would be lost when the app is restarted.

Option: accept_dns

This option allows you to accept the DNS settings of your tailnet that are configured on the DNS page of the admin console. When disabled, Tailscale's DNS resolves only tailnet addresses, no global nameservers from the admin console are applied.

For more information, see the "DNS" section of this documentation.

This option is enabled by default.

Option: accept_routes

This option allows you to accept subnet routes advertised by other nodes in your tailnet.

More information: Subnet routers

This option is disabled by default.

Option: advertise_connector

This option allows you to advertise this Tailscale instance as an app connector.

When you use an app connector, you specify which applications you wish to make accessible over your tailnet, and the domains for those applications. Any traffic for that application is then forced over the tailnet to a node running an app connector before egressing to the target domains. This is useful for cases where the application has an allowlist of IP addresses which can connect to it: the IP address of the node running the app connector can be added to the allowlist, and all nodes on the tailnet will use that IP address for their traffic egress.

More information: App connectors

This option is disabled by default.

Option: advertise_exit_node

This option allows you to advertise this Tailscale instance as an exit node.

By setting a device on your network as an exit node, you can use it to route all your public internet traffic as needed, like a consumer VPN.

More information: Exit nodes

This option is disabled by default.

Note: You can't advertise this device as an exit node and at the same time specify an exit node to use. See also the "Option: exit_node" section of this documentation.

Note: After you enable this option, you also have to enable it on Tailscale's admin console.

  1. Navigate to the Machines page of the admin console, and find your Home Assistant instance.

  2. Click on the … icon at the right side and select the "Edit route settings..." option. The "Exit node" and "Subnet routes" functions can be enabled here.

Option: advertise_routes

This option allows you to advertise routes to subnets (accessible on the network your device is connected to) to other clients on your tailnet.

By adding to the list the IP addresses and masks of the subnet routes, you can use it to make your devices on these subnets accessible within your tailnet.

More information: Subnet routers

Note: After you add subnets to this option, you also have to enable them on Tailscale's admin console.

  1. Navigate to the Machines page of the admin console, and find your Home Assistant instance.

  2. Click on the … icon at the right side and select the "Edit route settings..." option. The "Exit node" and "Subnet routes" functions can be enabled here.

Option: advertise_tags

This option allows you to specify specific tags for this Tailscale instance. They need to start with tag:.

More information: Tags

Option: always_use_derp

When enabled forces all peer communication over DERP by disabling the use of UDP.

This option is disabled by default.

Basically you will never want to enable this option. Try to enable it only, when you experience that connections to your Home Assistant device regularly freeze (even when you can ping the device, the web page or the Home Assistant app is unresponsive), and you have to reload the web page or force stop the Home Assistant app to make them work again. The root cause can be that your ISP erroneously drops UDP packets on certain conditions.

Option: exit_node

This option allows you to specify another Tailscale instance as an exit node for this device.

By setting a device on your network as an exit node, you can use it to route all your public internet traffic as needed, like a consumer VPN.

More information: Exit nodes

This option is unused by default. To make it visible on the configuration editor, click "Show unused optional configuration options" at the bottom of the page.

Note: You can't advertise this device as an exit node and at the same time specify an exit node to use. See also the "Option: advertise_exit_node" section of this documentation.

Note: The exit-node-allow-lan-access option is always enabled when an exit node is specified. This is required by the Home Assistant environment.

Option: log_suppression

This option allows you to suppress Tailscale's log messages in the app's log after 200 lines.

Turn it off only in case you are troubleshooting, because Tailscale is quite chatty.

This option is enabled by default.

Option: log_upload

Controls Tailscale's client log upload to log.tailscale.com. Enable it if your tailnet policy requires client log upload, otherwise Tailscale and the app can refuse to start.

Note: When disabled, turns on Tailscale's --no-logs-no-support flag.

This option is disabled by default.

Option: login_server

This option lets you to specify a custom control server instead of the default (https://controlplane.tailscale.com). This is useful if you are running your own Tailscale control server, for example, a self-hosted Headscale instance.

Option: share_homeassistant

This option allows you to enable Tailscale Serve or Funnel features to present your Home Assistant instance with a valid certificate on your tailnet or on the internet.

This option is disabled by default.

Tailscale can provide a TLS certificate for your Home Assistant instance within your tailnet domain.

This can prevent browsers from warning that HTTP URLs to your Home Assistant instance look unencrypted (browsers are not aware that the connections between Tailscale nodes are secured with end-to-end encryption).

Note: Tailscale Serve and Funnel will automatically update the certificate before expiration, unlike the tailscale cert command. Follow the steps in this documentation below to set up Serve or Funnel properly.

With the Tailscale Serve feature, you can access your Home Assistant instance with the provided certificate within your tailnet from devices already connected to your tailnet.

With the Tailscale Funnel feature, you can access your Home Assistant instance with the provided certificate not only within your tailnet but even from the wider internet using your Tailscale domain (like https://homeassistant.tail1234.ts.net) from devices without installed Tailscale VPN client (for example, on general phones, tablets, and laptops).

Client ⇒ Internet ⇒ Tailscale Funnel (TCP proxy) ⇒ VPN ⇒ Tailscale Serve (HTTPS proxy) → HA (HTTP web-server)

More information: Enabling HTTPS, Tailscale Serve, Tailscale Funnel.

Note: If you only want to expose Home Assistant on your tailnet, but with Tailscale Services, you can also configure it through the services option. However, the services option does not support Tailscale Funnel, only Tailscale Serve. If you need to access Home Assistant from the internet, use this option instead.

  1. Disable SSL/TLS so Home Assistant is accessible through an HTTP connection (this is the default). You can access this setting at Settings -> System -> Network -> HTTP server -> SSL/TLS

    Note: If you want to use another HTTPS connection to access Home Assistant, though Tailscale can access Home Assistant even if Home Assistant is using SSL and is accessible through an HTTPS connection, please use a reverse proxy app for that HTTPS connection instead of configuring Home Assistant to use SSL.

  2. Home Assistant, by default, blocks requests from reverse proxies, like the Tailscale Serve. To enable it, go to Settings -> System -> Network -> HTTP server -> Reverse proxy and edit the options below (don't forget to restart Home Assistant after the changes are saved):

    • Enable Trust X-Forwarded-For option.

    • Add "127.0.0.1" to the Trusted proxies option.

  3. Navigate to the DNS page of the admin console:

    • Choose a tailnet name.

    • Enable MagicDNS if not already enabled.

    • Under HTTPS Certificates section, click Enable HTTPS.

  4. Optionally, if you want to use Tailscale Funnel, navigate to the Access controls page of the admin console:

    • Add the required funnel node attribute to the tailnet policy file. See Funnel node attribute for more information.
  5. Restart the app.

Note: After initial setup, it can take up to 10 minutes for the domain to be publicly available.

Note: You should not use the port number in the URL that you used previously to access Home Assistant. Tailscale Serve and Funnel works on the default HTTPS port 443 (or the port configured in option share_on_port).

Note: If you encounter strange browser behaviour or strange error messages, try to clear all site-related cookies, clear all browser cache, and restart the browser.

Option: share_on_port

This option lets you specify which port the Tailscale Serve and Funnel features will use to present your Home Assistant instance on the tailnet and on the internet.

Only ports 443, 8443, and 10000 are allowed by Tailscale.

Port 443 is used by default.

Option: services

This option allows you to advertise other local services running on this device as Tailscale Services. Each service needs a name, a local target address, furthermore a protocol, and a port to expose it on.

This option is disabled by default.

Note: For Tailscale Services to work, this device must use tags. See the advertise_tags option for more information.

You can use this option to expose an app running on your Home Assistant instance, such as an audiobookshelf app, to your tailnet using a stable MagicDNS name.

  • The service name must include the svc: prefix.

  • The target must be a local address reachable from this app. Use http://, https:// or https+insecure:// targets for HTTP/HTTPS protocols, and tcp:// targets for TCP and tls-terminated-tcp protocols, for example http://127.0.0.1:13378.

  • Supported protocols by which the target will be presented:

    Note: For https and tls-terminated-tcp protocols you must enable MagicDNS and HTTPS certificates for your tailnet on the DNS page of the admin console first. Once enabled, Tailscale automatically provisions a TLS certificate for the service.

    • http: Expose the service as an HTTP server on the configured port.

    • https: Expose the service as an HTTPS server on the configured port.

    • tcp: Forward raw TCP packets to the configured target.

    • tls-terminated-tcp: Forward TLS-terminated TCP packets to the configured target.

  • The port is where the target will be exposed.

  • The path is where the target will be exposed. Optional, defaults to /, and can be used only for the HTTP/HTTPS protocols.

Before a service can accept traffic:

  1. You must define the Service on the Services page of the admin console.

  2. Restart the app.

  3. Approve this device as a Service host on the Services page of the admin console.

More information: Tailscale Services.

Option: snat_subnet_routes

This option allows subnet devices to see the traffic originating from the subnet router, and this simplifies routing configuration.

This option is enabled by default.

To support advanced Site-to-site networking (e.g. to traverse multiple networks), you can disable this functionality, and follow steps in the Site-to-site networking guide (Note: The app already handles "IP address forwarding" and "Clamp the MSS to the MTU" for you).

Note: Only disable this option if you fully understand the implications. Keep it enabled if preserving the real source IP address is not critical for your use case.

Option: stateful_filtering

This option enables stateful packet filtering on packet-forwarding nodes (exit nodes, subnet routers, and app connectors), to only allow return packets for existing outbound connections. Inbound packets that don't belong to an existing connection are dropped.

This option is disabled by default.

Option: taildrive

This option allows you to specify which Home Assistant directories you want to share with other Tailscale nodes using Taildrive.

Only the listed directories are available.

These options are disabled by default.

More information: Taildrive

Option: taildrop

This app supports Tailscale's Taildrop feature, which allows you to send files to your Home Assistant instance from other Tailscale devices.

This option is disabled by default.

Received files are stored in the /share/taildrop directory.

Option: userspace_networking

When enabled, Tailscale will not create a tailscale0 network interface on your host, i.e. you get one-way access from tailnet clients to your Home Assistant instance (and optionally the local subnets).

This option is disabled by default.

To be able to address other clients on your tailnet not only by their tailnet IP but also by their tailnet name, see the "DNS" section of this documentation.

If you want to access other clients on your tailnet even from your local subnet, follow steps in the Site-to-site networking guide (Note: The app already handles "IP address forwarding" and "Clamp the MSS to the MTU" for you). See also the "Option: snat_subnet_routes" section of this documentation.

More information: Userspace networking mode

Note: In case your local subnets collide with subnet routes within your tailnet, your local network access has priority, and these addresses won't be routed toward your tailnet. This will prevent your Home Assistant instance from losing network connection. This also means that using the same subnet on multiple nodes for load balancing and failover is impossible with the current app behavior.

Note: If you access Home Assistant directly via the tailnet, without using Serve or Funnel (ie. without using share_homeassistant or services options):

  • If you access Home Assistant with it's tailnet address (IP or url), and userspace_networking is disabled (default), Home Assistant sees incoming traffic originating from the tailnet (100.x.x.x addresses), in this case users need "local access only" to be disabled in their settings. Though when userspace_networking is enabled, Home Assistant sees incoming traffic originating from the localhost (127.0.0.1), and you don't need to disable "local access only".

  • On the other hand, if you access Home Assistant with it's LAN address (via subnet routing), and snat_subnet_routes is enabled (default), Home Assistant sees incoming traffic originating from it's LAN IP (whether userspace_networking is enabled or not), and you don't need to disable "local access only" in the users' settings.

Network

Port: 41641/udp

UDP port to listen on for WireGuard and peer-to-peer traffic.

Use this option (and router port forwarding) if you experience that Tailscale can't establish peer-to-peer connections to some of your devices (usually behind CGNAT networks). You can test connections with tailscale ping <hostname-or-ip>.

When not set, an automatically selected port is used by default.

DNS

When the userspace_networking option is disabled, Tailscale provides a DNS (at 100.100.100.100 and fd7a:115c:a1e0::53) to be able to address other clients on your tailnet not only by their tailnet IP but also by their tailnet name.

More information: What is 100.100.100.100, DNS in Tailscale, MagicDNS, Access a Pi-hole from anywhere.

  1. Check that the userspace_networking option is disabled.

  2. Check that under Settings -> System -> Network Tailscale's DNS is not configured as a DNS server.

  3. In the command line, execute ha dns options --servers dns://100.100.100.100.

    Note: This command replaces the existing DNS server list in Home Assistant and restarts the internal DNS server. To specify an empty DNS list (i.e. to remove dns://100.100.100.100 from the list), you must use ha dns reset and ha dns restart commands both. This server list is additional and queried before the DNS servers specified in Network settings above. This configuration is persistent, you have to execute it only once.

Note: The only difference compared to the general Tailscale experience, is that you always have to use the fully qualified domain name instead of only the device name, i.e. ping some-tailnet-device.tail1234.ts.net works, but ping some-tailnet-device does not work.

Changelog & Releases

This repository keeps a change log using GitHub's releases functionality.

Releases are based on Semantic Versioning, and use the format of MAJOR.MINOR.PATCH. In a nutshell, the version will be incremented based on the following:

  • MAJOR: Incompatible or major changes.
  • MINOR: Backwards-compatible new features and enhancements.
  • PATCH: Backwards-compatible bugfixes and package updates.

Support

Got questions?

You have several options to get them answered:

You could also open an issue here GitHub.

Authors & contributors

The original setup of this repository is by Franck Nijhof.

For a full list of all authors and contributors, check the contributor's page.

License

MIT License

Copyright (c) 2021-2026 Franck Nijhof

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.