Ansible Role for Headscale

This role installs and manages Headscale on Linux systems.

Requirements

• Ansible version 7 or higher

Installation

To install the role, run:

ansible-galaxy install kazauwa.headscale

Role Variables

• headscale_version

  • Default: 0.22.3
  • Description: The version of Headscale to install. You can find available versions on the official releases page. This defaults to the latest version.

• headscale_arch

  • Default: amd64
  • Description: The architecture for the Headscale binary.

• headscale_os

  • Default: linux
  • Description: The operating system for the Headscale binary.

• headscale_user_name

  • Default: headscale
  • Description: The username for the service user that runs the Headscale binary.

• headscale_user_group

  • Default: headscale
  • Description: The group for the service user that runs the Headscale binary.

• headscale_user_uid

  • Default: 800
  • Description: The user ID for the service user that runs the Headscale binary.

• headscale_user_gid

  • Default: 800
  • Description: The group ID for the service user that runs the Headscale binary.

• headscale_binary_path

  • Default: /usr/local/bin/headscale
  • Description: The installation path for the Headscale binary.

• headscale_config_dir

  • Default: /etc/headscale
  • Description: The path where Headscale configuration files are stored.

• headscale_var_data_dir

  • Default: /var/lib/headscale
  • Description: The path for Headscale data storage.

• headscale_pid_dir

  • Default: /var/run/headscale
  • Description: The path for Headscale socket files.

• headscale_config

  • Default: {}
  • Description: YAML-formatted configuration for Headscale. You may refer to the default config for guidance.

• headscale_config_template

  • Default: ""
  • Description: The path to a Jinja2 formatted template for the Headscale config. If specified, this will replace headscale_config.

• headscale_acl

  • Default: {}
  • Description: YAML-formatted Access Control Lists (ACL) policies. Ensure you read the documentation on using this feature.

• headscale_users

  • Default: []
  • Description: A list of users to create, useful for tagOwners functionality.

• headscale_enable_routes

  • Default: []
  • Description: A list of nodes with routes to enable. This accepts an integer ID of a Headscale node, a list of comma-separated routes, and an optional comment. Used when autoApprovers are not set.
  • Example: {'id': 14, 'routes': '10.0.0.0/24,10.2.3.4/32', 'comment': 'Gateway to prod'}

• headscale_exit_nodes

  • Default: []
  • Description: A list of nodes operating as exit nodes. This accepts an integer ID of a Headscale node, along with an optional comment. Used when autoApprovers are not set.
  • Example: {'id': 14, 'comment': 'eu-fra-01'}

Dependencies

No dependencies.

Example Playbook

Here's an example of using this role in a playbook:

- hosts: all
  roles:
    - kazauwa.headscale
  vars:
    headscale_version: '0.22.3'

License

MIT License