Skip to content

Headscale

Headscale is a self-hosted, open-source coordination server for Tailscale. Instead of relying on Tailscale's proprietary cloud service, we run Headscale on an Oracle Cloud VM. It uses the same WireGuard protocol as Tailscale, however, it allows for us to have an unlimited number of users and devices, as well as manage it via IaC with Terraform.

Connecting to the VM

Under normal circumstances to add and remove users you don't need to connect to the cloud VM, however if you do need to for updates, the ssh keys can be found in the Cyber@UC Google drive and can be connected to via the opc user

Add Users to Headscale

Adding users to the Headscale VPN is a straightforward process managed via Terraform. To add a new user, you only need to edit the users.tfvars file within the Headscale GitLab project.

The GitLab pipeline will automatically generate access tokens for the new user after the deploy stage is complete.

Instructions

  1. Navigate to the Headscale GitLab project.
  2. Open and edit the users.tfvars file.

  3. Add the new user's name following the firstname-lastname naming convention. For example:

    user_list = [
    "cyberatuc",
    "cooper-pflaum",
    "hugh-sweazy",
]

  4. Commit your changes. The pipeline will then run and generate the necessary access tokens.

The cyberatuc and mark-dts users are required and are protected from accidental deletion

Connecting to Headscale

After the tokens are generated, you can find instructions on how to connect a device to Headscale here.

How To Update The Container

  1. Locate the docker compose file under /home/opc/headscale
  2. Edit the docker-compose.yaml file (Vim or Nano)
  3. Change the line that says image: docker.io/headscale/headscale:v0.x to current released version
  4. Run the commands docker compose pull and then docker compose up -d to restart the container
  5. Verify connectivity

Make sure that you don't set the version to a rolling version to keep compatibility with terraform

Example full docker compose file: 

services:
  headscale:
    # https://hub.docker.com/r/headscale/headscale/tags
    image: docker.io/headscale/headscale:v0.26
    restart: unless-stopped
    container_name: headscale
    ports:
      - "0.0.0.0:8080:8080"
      - "0.0.0.0:443:443"
      - "0.0.0.0:9090:9090"
    volumes:
      - /etc/headscale:/etc/headscale
      - /var/lib/headscale:/var/lib/headscale
      - /var/run/headscale:/var/run/headscale
    command: serve

Refreshing the API Key

If you encounter an API key-related error, it likely needs refreshed. The current key is set to expire in May 2028, but if it expires or is compromised, you can generate a new one.

Instructions

  1. View existing keys: To see the list of current API keys, run the following command on the Headscale server:

    headscale apikeys list

  2. Generate a new key: Create a new API key with the following command:

    headscale apikeys create

    Copy the value that is returned, as it will not be displayed again.

  3. Update the GitLab variable: Go to the Headscale GitLab project's CICD settings, navigate to the Variables section, and update the value for the API_KEY variable with the new key you just generated.