5ba78886d2
- Add automatic SD image builds for Raspberry Pi via Forgejo Actions - Enable binfmt emulation on cryodev-main for aarch64 cross-builds - Add sd-image.nix module to cryodev-pi configuration - Create comprehensive docs/ structure with installation guides - Split installation docs into: first-install (server), reinstall, new-client (Pi) - Add lib/utils.nix and apps/rebuild from synix - Fix headplane module for new upstream API (tale/headplane) - Fix various module issues (mailserver stateVersion, option conflicts) - Add placeholder secrets.yaml files for both hosts - Remove old INSTRUCTIONS.md (content moved to docs/)
116 lines
1.8 KiB
Markdown
116 lines
1.8 KiB
Markdown
# 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
|