arillso.agent.tailscale role – Install and configure Tailscale VPN for mesh networking

Note

This role is part of the arillso.agent collection (version 2.1.0).

It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it use: ansible-galaxy collection install arillso.agent.

To use it in a playbook, specify: arillso.agent.tailscale.

Entry point main – Install and configure Tailscale VPN for mesh networking

Synopsis

  • This role installs and configures Tailscale VPN via official package sources for creating secure mesh networks between devices and infrastructure. All configuration is persistent via /etc/tailscale/config.json daemon config file.

Parameters

Parameter

Comments

tailscale_accept_dns

string

Accept DNS configuration from tailnet (true/false)

Default: ""

tailscale_accept_routes

string

Accept subnet routes advertised by other nodes (true/false)

Default: ""

tailscale_advertise_connector

string

Advertise as app connector for domain-based routing (true/false)

Default: ""

tailscale_advertise_exit_node

string

Advertise this node as an exit node (true/false)

Default: ""

tailscale_advertise_routes

list / elements=string

Subnet routes to advertise in CIDR format (e.g., ‘192.168.1.0/24’)

Default: []

tailscale_advertise_services

list / elements=string

Services to advertise (e.g., ‘svc:my-api’)

Default: []

tailscale_auth_key

string / required

Tailscale authentication key for initial device registration (tskey-auth-* or tskey-reusable-*)

tailscale_auto_update_apply

string

Enable automatic update application (true/false)

Default: ""

tailscale_auto_update_check

string

Enable automatic update checking (true/false)

Default: ""

tailscale_config_dir

string

Directory path for Tailscale configuration files

Default: "/etc/tailscale"

tailscale_config_enabled

boolean

Enable persistent daemon configuration via config.json

Choices:

  • false

  • true ← (default)

tailscale_config_file

string

Path to Tailscale daemon configuration file

Default: "/etc/tailscale/config.json"

tailscale_daemon_enabled

string

Daemon config key: sets ‘enabled’ in config.json (true/false)

Default: ""

tailscale_enabled

boolean

Master switch: set to false to skip the role entirely

Choices:

  • false

  • true ← (default)

tailscale_exit_node

string

Exit node to use (IP, stable node ID, or MagicDNS name)

Default: ""

tailscale_exit_node_allow_lan_access

string

Allow direct LAN access when using exit node (true/false)

Default: ""

tailscale_hostname

string

Custom hostname for this device in Tailscale network

Default: ""

tailscale_locked

string

Lock config to prevent CLI changes (true/false)

Default: ""

tailscale_netfilter_mode

string

Firewall management mode: ‘on’ (default), ‘off’, or ‘nodivert’

Choices:

  • "" ← (default)

  • "on"

  • "off"

  • "nodivert"

tailscale_no_log_auth_key

boolean

no_log toggle for the auth-key task; set false to surface a join error hidden as ‘non-zero return code’.

Choices:

  • false

  • true ← (default)

tailscale_operator_user

string

Unix username allowed to operate tailscale without root

Default: ""

tailscale_package_name

string

Name of the Tailscale package to install

Default: "tailscale"

tailscale_package_state

string

Desired state of the Tailscale package

Choices:

  • "present" ← (default)

  • "absent"

  • "latest"

tailscale_posture_checking

string

Enable device posture data collection (true/false)

Default: ""

tailscale_preferences

dictionary

Custom Tailscale preferences via ‘tailscale set’ (advanced users only)

Default: {}

tailscale_reset_authentication

boolean

Perform logout and re-authentication (WARNING: temporary disconnect)

Choices:

  • false ← (default)

  • true

tailscale_server_url

string

Custom control server URL (default: https://controlplane.tailscale.com)

Default: ""

tailscale_service_enabled

boolean

Whether the tailscaled service should be enabled on boot

Choices:

  • false

  • true ← (default)

tailscale_service_override

dictionary

Dictionary of systemd service override parameters for tailscaled.service. Default includes ExecStart override to enable daemon config file support. Supports both Unit and Service section directives: - Unit directives: After, Before, Wants, Requires, PartOf, Conflicts, etc. - Service directives: ExecStart, ExecStartPre, Environment, etc. Examples: - Override ExecStart: tailscale_service_override: {ExecStart: [“”, “/custom/path”]} - Add environment: tailscale_service_override: {Environment: {VAR: “value”}} - Add dependencies: tailscale_service_override: {After: [“network.target”]} - Disable config: tailscale_service_override: {} (empty dict)

Default: {"ExecStart": ["", "/usr/sbin/tailscaled --state=/var/lib/tailscale/tailscaled.state --socket=/run/tailscale/tailscaled.sock --port=${PORT} --config={{ tailscale_config_file }}"]}

tailscale_service_state

string

Desired state of the tailscaled service

Choices:

  • "started" ← (default)

  • "stopped"

  • "restarted"

  • "reloaded"

tailscale_shields_up

string

Block all incoming connections from tailnet (true/false)

Default: ""

tailscale_snat_subnet_routes

string

Enable source NAT for advertised routes (true/false)

Default: ""

tailscale_ssh_enabled

string

Enable Tailscale SSH server (true/false)

Default: ""

tailscale_stateful_filtering

string

Enable stateful packet filtering (true/false)

Default: ""

tailscale_static_endpoints

list / elements=string

WireGuard endpoints in ‘<address>:<port>’ format

Default: []

tailscale_tags

list / elements=string

List of Tailscale tags for ACL-based access control (e.g., ‘tag:gateway’)

Default: []

tailscale_verify_connectivity

boolean

Run the connectivity verification phase (requires a running, authenticated tailscaled)

Choices:

  • false

  • true ← (default)

tailscale_version

string

Version of the Tailscale package to pin on apt and dnf hosts. Every run moves the host to exactly this version, downgrades included. An empty string installs whatever the repository offers and leaves later upgrades to the host.

Default: "1.104.4"

tailscale_webclient_enabled

string

Enable web client interface on port 5252 (true/false)

Default: ""

Authors

  • Simon Bärlocher