# Headscale

Headscale is an open-source, self-hosted implementation of the Tailscale control server.

## References

- [Website](https://headscale.net/stable/)
- [GitHub](https://github.com/juanfont/headscale)
- [Example configuration](https://github.com/juanfont/headscale/blob/main/config-example.yaml)

## Setup

### DNS

Set a CNAME record for `headscale.cryodev.xyz` pointing to your main domain.

### Configuration

```nix
# hosts/cryodev-main/services/headscale.nix
{
  services.headscale = {
    enable = true;
    openFirewall = true;
  };
}
```

## Usage

### Create a User

```bash
sudo headscale users create <USERNAME>
```

### List Users

```bash
sudo headscale users list
```

### Create Pre-Auth Key

```bash
sudo headscale preauthkeys create --expiration 99y --reusable --user <USER_ID>
```

The pre-auth key is used by clients to automatically authenticate and join the tailnet.

### List Nodes

```bash
sudo headscale nodes list
```

### Delete a Node

```bash
sudo headscale nodes delete -i <NODE_ID>
```

### Rename a Node

```bash
sudo headscale nodes rename -i <NODE_ID> new-name
```

## ACL Configuration

Access Control Lists define which nodes can communicate with each other.

### Validate ACL File

```bash
sudo headscale policy check --file /path/to/acl.hujson
```

### Example ACL

```json
{
  "acls": [
    {
      "action": "accept",
      "src": ["*"],
      "dst": ["*:*"]
    }
  ]
}
```

## Troubleshooting

### Check Service Status

```bash
sudo systemctl status headscale
```

### View Logs

```bash
sudo journalctl -u headscale -f
```

### Test DERP Connectivity

```bash
curl -I https://headscale.cryodev.xyz/derp
```

## Integration

- [Headplane](headplane.md) - Web UI for managing Headscale
- [Tailscale Client](tailscale.md) - Connect clients to Headscale