hampusstrom.headscale

Ansible Role: Headscale

This Ansible role is for installing and setting up Headscale, an open-source, self-hosted version of the Tailscale control server.

Check it out here: juanfont/Headscale

Disclaimer

The author is not associated with the Headscale project or Tailscale Inc.

This software is provided "as is," with no guarantees of any kind, including but not limited to merchantability and fitness for a particular purpose. The author is not responsible for any claims or damages arising from the use of this software.

Use at your own risk.

Compatibility

This role has been tested on:

CentOS 8 x64
Debian 10 x64
Debian 11 x64
Ubuntu Server 20.04 x64
Ubuntu Server 22.04 x64

Installation

Using ansible-galaxy

ansible-galaxy install hampusstrom.headscale

Manual Installation

For the current user:

git clone https://github.com/hampusstrom/ansible-role-headscale.git ~/.ansible/roles/hampusstrom.headscale

For the entire system:

git clone https://github.com/hampusstrom/ansible-role-headscale.git /etc/ansible/roles/hampusstrom.headscale

Requirements

This role requires standard components and should work anywhere Ansible, Headscale, and systemd run.

GitHub API

This role uses the GitHub API, which has request limits. Unauthenticated users can only make 60 requests per hour. Developers may hit this limit easily.

To avoid this, get a Personal Access Token from: https://github.com/settings/tokens/new

Fill in your GitHub details in the headscale_github_api_* variables.

Init system: systemd

Root access required: yes

Root access is necessary. Use this role in a playbook with become: yes defined globally or call it with become: yes. Here's how to do it in YAML:

- hosts: headscale
  become: yes
  roles:
    - role: hampusstrom.headscale

Role Variables

You can find a detailed description of all available variables in defaults/main.yaml.

Variable Naming Convention

Variables for this role start with headscale_.

headscale_version

Specifies the version of Headscale to download. Acceptable values include a version number (like 0.16.4) or latest.

Default: latest

headscale_config

This is the configuration for the Headscale config.yaml file, expressed as a yaml object. Refer to the default config in the Headscale project for examples.

Minimum values for version 0.20.0 are required as follows:

headscale_config:
  server_url: "http://127.0.0.1:8080"
  listen_addr: 127.0.0.1:8080
  private_key_path: "{{ headscale_lib_dir_path }}/private.key"
  db_type: sqlite3
  unix_socket: "{{ headscale_run_dir_path }}/headscale.sock"
  ip_prefixes:
    - 100.64.0.0/10
  noise:
    private_key_path: "{{ headscale_lib_dir_path }}/noise_private.key"

Other Important Variables

headscale_acl: Configuration for the Headscale acl.yaml file.
headscale_github_repository: Repository for downloading the Headscale binary. Default: juanfont/headscale.
headscale_remove_unmanaged_users: If true, users not in headscale_users will be deleted. Default: false.
headscale_users: List of users to create. Default: [].
headscale_binary_path: Defines where to install the Headscale binary. Default: /usr/local/bin/headscale.
headscale_user_name: Name of the system user that runs the Headscale service. Default: headscale.
Additional variables are available for configurations related to database paths, library paths, TLS settings, and more.

Example Playbook

Always consult the official Headscale documentation to ensure you have the proper values for your version. You can use this as a base for your configuration:

---
# Run with:
# ansible-playbook -i "yourinventoryfile" -K example-playbook.yml
- hosts: all
  become: yes
  vars:
    headscale_version: 0.20.0
    headscale_config:
      server_url: http://127.0.0.1:8080
      listen_addr: 127.0.0.1:8080
      ...
  roles:
    - hampusstrom.headscale