From 715fe84ceaa7426ba577e468f1b45ce5685841f2 Mon Sep 17 00:00:00 2001 From: Laszlo Magyar Date: Mon, 23 Oct 2023 19:59:54 +0100 Subject: [PATCH] Documentation improvements (#274) --- tailscale/DOCS.md | 69 ++++++++++--------- tailscale/config.yaml | 3 +- .../s6-overlay/s6-rc.d/post-tailscaled/run | 8 +-- .../rootfs/etc/s6-overlay/s6-rc.d/proxy/run | 2 +- .../etc/s6-overlay/s6-rc.d/tailscaled/run | 2 +- .../rootfs/etc/s6-overlay/s6-rc.d/web/run | 2 +- .../etc/s6-overlay/scripts/stage2_hook.sh | 2 +- tailscale/translations/en.yaml | 4 +- 8 files changed, 47 insertions(+), 45 deletions(-) diff --git a/tailscale/DOCS.md b/tailscale/DOCS.md index 47ecfa4a..4b92b372 100644 --- a/tailscale/DOCS.md +++ b/tailscale/DOCS.md @@ -49,9 +49,9 @@ network right from their interface. The add-on exposes "Exit Node" capabilities that you can enable from your -Tailscale account. Additionally, if the Supervisor managed your network ( -which is the default), the add-on will also advertise routes to your -subnets on all supported interfaces to Tailscale. +Tailscale account. Additionally, if the Supervisor managed your network (which +is the default), the add-on will also advertise routes to your subnets on all +supported interfaces to Tailscale. Consider disabling key expiry to avoid losing connection to your Home Assistant device. See [Key expiry][tailscale_info_key_expiry] for more information. @@ -60,10 +60,10 @@ device. See [Key expiry][tailscale_info_key_expiry] for more information. accept_dns: true accept_routes: true advertise_exit_node: true -funnel: false advertise_routes: - 192.168.1.0/24 - fd12:3456:abcd::/64 +funnel: false log_level: info login_server: "https://controlplane.tailscale.com" proxy: false @@ -92,7 +92,7 @@ by adding `100.100.100.100` as a DNS server in your Pi-hole or AdGuard Home. This option allows you to accept subnet routes advertised by other nodes in your tailnet. -More information: +More information: [Subnet routers][tailscale_info_subnets] When not set, this option is enabled by default. @@ -103,7 +103,7 @@ 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: +More information: [Exit nodes][tailscale_info_exit_nodes] When not set, this option is enabled by default. @@ -191,32 +191,9 @@ you are troubleshooting. ### Option: `login_server` -This option lets you specify 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: `userspace_networking` - -The add-on uses [userspace networking mode][tailscale_info_userspace_networking] -to make your Home Assistant instance (and optionally the local subnets) -accessible within your tailnet. - -When not set, this option is enabled by default. - -If you need to access other clients on your tailnet from your Home Assistant -instance, disable userspace networking mode, which will create a `tailscale0` -network interface on your host. - -If you want to access other clients on your tailnet even from your local subnet, -execute steps 2 and 3 as described on [Site-to-site -networking][tailscale_info_site_to_site]. - -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 add-on behavior. +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: `proxy` @@ -249,7 +226,7 @@ More information: [Enabling HTTPS][tailscale_info_https] 1. Navigate to the [DNS page][tailscale_dns] of the admin console: - - Choose a Tailnet name. + - Choose a tailnet name. - Enable MagicDNS if not already enabled. @@ -277,7 +254,7 @@ only when you really understand why you need this. This option allows you to specify specific ACL tags for this Tailscale instance. They need to start with `tag:`. -More information: +More information: [ACL tags][tailscale_info_acls] ### Option: `taildrop` @@ -289,6 +266,28 @@ When not set, this option is enabled by default. Received files are stored in the `/share/taildrop` directory. +### Option: `userspace_networking` + +The add-on uses [userspace networking mode][tailscale_info_userspace_networking] +to make your Home Assistant instance (and optionally the local subnets) +accessible within your tailnet. + +When not set, this option is enabled by default. + +If you need to access other clients on your tailnet from your Home Assistant +instance, disable userspace networking mode, which will create a `tailscale0` +network interface on your host. + +If you want to access other clients on your tailnet even from your local subnet, +execute steps 2 and 3 as described on [Site-to-site +networking][tailscale_info_site_to_site]. + +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 add-on behavior. + ## Changelog & Releases This repository keeps a change log using [GitHub's releases][releases] @@ -365,9 +364,11 @@ SOFTWARE. [tailscale_acls]: https://login.tailscale.com/admin/acls [tailscale_dns]: https://login.tailscale.com/admin/dns [tailscale_info_acls]: https://tailscale.com/kb/1068/acl-tags/ +[tailscale_info_exit_nodes]: https://tailscale.com/kb/1103/exit-nodes/ [tailscale_info_funnel]: https://tailscale.com/kb/1223/tailscale-funnel/ [tailscale_info_funnel_policy_requirement]: https://tailscale.com/kb/1223/tailscale-funnel/#tailnet-policy-file-requirement [tailscale_info_https]: https://tailscale.com/kb/1153/enabling-https/ [tailscale_info_key_expiry]: https://tailscale.com/kb/1028/key-expiry/ [tailscale_info_site_to_site]: https://tailscale.com/kb/1214/site-to-site/ +[tailscale_info_subnets]: https://tailscale.com/kb/1019/subnets/ [tailscale_info_userspace_networking]: https://tailscale.com/kb/1112/userspace-networking/ diff --git a/tailscale/config.yaml b/tailscale/config.yaml index cab42f64..e0c377bc 100644 --- a/tailscale/config.yaml +++ b/tailscale/config.yaml @@ -36,6 +36,7 @@ schema: login_server: url? proxy: bool? snat_subnet_routes: bool? - tags: ["match(^tag:[a-zA-Z0-9]-?[a-zA-Z0-9]+$)?"] + tags: + - "match(^tag:[a-zA-Z0-9]-?[a-zA-Z0-9]+$)?" taildrop: bool? userspace_networking: bool? diff --git a/tailscale/rootfs/etc/s6-overlay/s6-rc.d/post-tailscaled/run b/tailscale/rootfs/etc/s6-overlay/s6-rc.d/post-tailscaled/run index 90ee0c77..11e5df47 100755 --- a/tailscale/rootfs/etc/s6-overlay/s6-rc.d/post-tailscaled/run +++ b/tailscale/rootfs/etc/s6-overlay/s6-rc.d/post-tailscaled/run @@ -89,6 +89,8 @@ do sleep 2 done +bashio::log.info "Tailscale is running" + # Warn about key expiration if keyexpiry=$(/opt/tailscale status --self=true --peers=false --json | jq -rce '.Self.KeyExpiry'); then bashio::log.warning "The connection's key will expire on: ${keyexpiry}" @@ -96,8 +98,6 @@ if keyexpiry=$(/opt/tailscale status --self=true --peers=false --json | jq -rce bashio::log.warning "Please check your configuration based on the add-on's documentation under \"Configuration\"" fi -bashio::log.info "Tailscale is running" - # Warn about colliding subnet routes if non-userspace networking and accepting routes are enabled if bashio::config.false "userspace_networking" && \ (! bashio::config.has_value "accept_routes" || \ @@ -120,12 +120,12 @@ then done fi -# Warn about userspace networking +# Notify about userspace networking if ! bashio::config.has_value "userspace_networking" || \ bashio::config.true "userspace_networking"; then bashio::log.notice "The add-on uses userspace networking mode." bashio::log.notice "If you need to access other clients on your tailnet from your Home Assistant instance," bashio::log.notice "disable userspace networking mode, that will create a \"tailscale0\" network interface on your host." - bashio::log.notice "Please check your configuration based on the add-on's Documentation under \"Option: userspace_networking\"" + bashio::log.notice "Please check your configuration based on the add-on's documentation under \"Option: userspace_networking\"" fi diff --git a/tailscale/rootfs/etc/s6-overlay/s6-rc.d/proxy/run b/tailscale/rootfs/etc/s6-overlay/s6-rc.d/proxy/run index 1dfb9dbe..23e0277a 100755 --- a/tailscale/rootfs/etc/s6-overlay/s6-rc.d/proxy/run +++ b/tailscale/rootfs/etc/s6-overlay/s6-rc.d/proxy/run @@ -51,7 +51,7 @@ if bashio::config.true 'proxy'; then bashio::exit.nok fi bashio::log.info "Tailscale Proxy is enabled:" - bashio::log.info " Your Home Assistant instance is available within your Tailnet VPN at" + bashio::log.info " Your Home Assistant instance is available within your tailnet VPN at" bashio::log.info " https://${domain}" fi diff --git a/tailscale/rootfs/etc/s6-overlay/s6-rc.d/tailscaled/run b/tailscale/rootfs/etc/s6-overlay/s6-rc.d/tailscaled/run index 558fdb7b..bbb52847 100755 --- a/tailscale/rootfs/etc/s6-overlay/s6-rc.d/tailscaled/run +++ b/tailscale/rootfs/etc/s6-overlay/s6-rc.d/tailscaled/run @@ -28,7 +28,7 @@ if bashio::debug ; then exec /opt/tailscaled "${options[@]}" else bashio::log.notice \ - "Tailscale logs will be suppressed after 200 lines, set add-on's "\ + "Tailscale logs will be suppressed after 200 lines, set add-on's" \ "configuration option 'log_level' to 'debug' to see further logs" /opt/tailscaled "${options[@]}" 2>&1 \ diff --git a/tailscale/rootfs/etc/s6-overlay/s6-rc.d/web/run b/tailscale/rootfs/etc/s6-overlay/s6-rc.d/web/run index 1c424231..e5c20a8d 100755 --- a/tailscale/rootfs/etc/s6-overlay/s6-rc.d/web/run +++ b/tailscale/rootfs/etc/s6-overlay/s6-rc.d/web/run @@ -3,7 +3,7 @@ # ============================================================================== # Home Assistant Community Add-on: Tailscale # Runs tailscale web interface -# ============================================================================= +# ============================================================================== declare -a options bashio::log.info 'Starting Tailscale web...' diff --git a/tailscale/rootfs/etc/s6-overlay/scripts/stage2_hook.sh b/tailscale/rootfs/etc/s6-overlay/scripts/stage2_hook.sh index 6aa761f5..9b97b5ed 100755 --- a/tailscale/rootfs/etc/s6-overlay/scripts/stage2_hook.sh +++ b/tailscale/rootfs/etc/s6-overlay/scripts/stage2_hook.sh @@ -21,7 +21,7 @@ then rm /etc/s6-overlay/s6-rc.d/user/contents.d/mss-clamping fi -# Disable taildrop service when it is has been explicitly disabled +# Disable taildrop service when it has been explicitly disabled if bashio::config.false 'taildrop'; then rm /etc/s6-overlay/s6-rc.d/user/contents.d/taildrop fi diff --git a/tailscale/translations/en.yaml b/tailscale/translations/en.yaml index 35cd1ce2..1c01595c 100644 --- a/tailscale/translations/en.yaml +++ b/tailscale/translations/en.yaml @@ -7,7 +7,7 @@ configuration: disable, you can do so using this option. When not set, this option is enabled by default. accept_routes: - name: Accept Routes + name: Accept routes description: >- This option allows you to accept subnet routes advertised by other nodes in your tailnet. @@ -73,7 +73,7 @@ configuration: name: Userspace networking mode description: >- This option allows you to enable userspace networking mode. - If you need to access other clients on your Tailnet from your Home + If you need to access other clients on your tailnet from your Home Assistant instance, disable userspace networking mode, which will create a `tailscale0` network interface on your host. When not set, this option is enabled by default.