Tailscale2Headscale/README.md

# Tailscale2Headscale
# Headscale + Tailscale – Homelab Migration

> ⚠️ **Version publique / anonymisée**
> Tous les noms de domaine, IP et clés ont été remplacés par des **placeholders**.
> Remplace toutes les valeurs `<...>` par les tiennes avant d’utiliser ce document.

---

## 1. Objectif

Mettre en place un **contrôle Tailscale auto‑hébergé** avec **Headscale** pour remplacer le control plane Tailscale SaaS, tout en :

- gardant les clients Tailscale classiques (Linux, macOS, Android, Home Assistant, etc.) ;
- centralisant la gestion sur un serveur Headscale accessible en HTTPS ;
- évitant les bugs classiques (mauvais port, mauvais `--login-server`, clés expirées, etc.).

Ce README récapitule :

- l’architecture retenue ;
- la configuration Headscale (service + Web admin + reverse proxy) ;
- la configuration des clients Tailscale ;
- les problèmes rencontrés et les solutions pour ne plus tomber dedans.

---

## 2. Architecture globale

### 2.1. Composants

- **Serveur Headscale**

  - Type : LXC / VM Linux (Debian‑like)
  - Rôle : serveur `headscale` + Web UI (headscale‑admin)
  - IP locale : `<HEADSCALE_LAN_IP>` (ex : `192.168.1.xxx`)
  - Nom interne : `<HEADSCALE_HOSTNAME>` (ex : `headscale`)
- **Reverse proxy (facultatif mais recommandé)**

  - Logiciel : `caddy` (ou nginx/traefik)
  - Port HTTP interne Headscale : `8080`
  - Port HTTPS public : `443`
  - Nom de domaine : `<HEADSCALE_PUBLIC_FQDN>` (ex : `headscale.example.com`)
  - Certificats : Let’s Encrypt ou équivalent
- **Clients Tailscale**

  - Serveur Proxmox VE : `<PVE_HOST>`
  - Proxmox Backup Server : `<PBS_HOST>`
  - NAS (OMV ou autre) : `<NAS_HOST>`
  - Containers / VM : `<CT_DOCKER_PTR>`, `<CT_JENKINS>`, etc.
  - Home Assistant : Add-on Tailscale
  - macOS : client Tailscale officiel
  - Android : app Tailscale officielle

Tout ce petit monde parle au **contrôle plane** : `https://<HEADSCALE_PUBLIC_FQDN>`.

---

## 3. Installation de Headscale (serveur)

### 3.1. Pré‑requis

Sur la machine Headscale (LXC/VM) :

```bash
apt update
apt install -y headscale sqlite3 ca-certificates curl
```

Créer le répertoire de configuration :

```bash
mkdir -p /etc/headscale
```

### 3.2. Fichier de configuration `config.yaml` (exemple)

> ⚠️ **Important :** Adapter les valeurs `server_url`, `listen_addr`, `grpc_listen_addr`, `db_path`, etc.

```yaml
# /etc/headscale/config.yaml
server_url: "https://<HEADSCALE_PUBLIC_FQDN>"
listen_addr: "0.0.0.0:8080"
grpc_listen_addr: "0.0.0.0:50443"

ip_prefixes:
  - "100.64.0.0/10"

derp:
  server:
    enabled: true
    region_id: 999
    region_code: "homelab"
    region_name: "Homelab DERP"
  paths: []

# Base SQLite (simple à gérer pour un homelab)
db_type: "sqlite"
db_path: "/var/lib/headscale/db.sqlite"

tls_cert_path: ""
tls_key_path: ""

log:
  level: "info"

dns_config:
  override_local_dns: false
  magic_dns: false
```

### 3.3. Service systemd

Le paquet Debian fournit généralement un service `headscale.service`.
Vérifier :

```bash
systemctl enable --now headscale
systemctl status headscale --no-pager
```

---

## 4. Web admin : headscale‑admin

### 4.1. Dossier et configuration

Headscale‑admin est en général servi par un serveur web (caddy/nginx), souvent depuis :

```bash
/var/www/headscale-admin
```

ou :

```bash
/opt/headscale-admin
```

Cette UI se connecte à l’API Headscale (port `8080` dans notre cas).

---

## 5. Reverse proxy (Caddy)

> C’est ici qu’on a eu une galère : mélange de ports `80` et `8080`.
> Résultat : clients Tailscale qui pointaient sur `:8080` alors que le proxy écoutait en `:80` → 404 ou connexion impossible.

### 5.1. Exemple de config Caddy

```bash
# /etc/caddy/Caddyfile

<HEADSCALE_PUBLIC_FQDN> {
    encode gzip

    # Proxy API Headscale (port interne 8080)
    reverse_proxy /api/* 127.0.0.1:8080

    # UI headscale-admin statique
    root * /var/www/headscale-admin
    file_server
}
```

### 5.2. Points critiques

- Le **serveur Headscale** écoute sur `:8080`.
- Le **reverse proxy** écoute en **:443** (et :80 pour HTTP → redirect vers 443).
- Les clients Tailscale **n’ont pas besoin du port** dans `--login-server` s’ils passent par HTTPS standard :`--login-server=https://<HEADSCALE_PUBLIC_FQDN>`
- Si tu décides de garder un port non standard (`:8443` par ex.), **il faut le mettre partout** :
  - dans `server_url` de Headscale ;
  - dans `--login-server=` côté clients ;
  - dans la config du reverse proxy.

---

## 6. Gestion des utilisateurs et clés dans Headscale

### 6.1. Créer un user

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

Exemple :

```bash
headscale users create syleric
```

### 6.2. Créer une preauth key

```bash
headscale preauthkeys create --user <USER_ID> --reusable --ephemeral=false
```

Exemple :

```bash
headscale users list
# ID | Name | Username | Email | Created
# 1  |      | $user  |       | ...

headscale preauthkeys create --user 1 --reusable --ephemeral=false
# -> renvoie une clé du type : 548fd8... (ne pas mettre ici en clair)
```

> 🔁 Si tu doutes d’une clé, tu peux la **regénérer** et supprimer l’ancienne.

---

## 7. Enregistrement des clients Tailscale

### 7.1. Schéma global

Pour chaque machine, on fait :

```bash
tailscale logout || true
tailscale down || true

tailscale up \
  --login-server=https://<HEADSCALE_PUBLIC_FQDN> \
  --auth-key=<PREAUTH_KEY> \
  --accept-dns=false \
  --accept-routes=false \
  --reset
```

> On utilise `--accept-dns=false` pour éviter que Headscale override le DNS local du homelab,
> et `--accept-routes=false` tant qu’on ne met pas en place de routes subnets poussées via Headscale.

---

## 8. Cas particulier : macOS

### 8.1. Utiliser le binaire Tailscale macOS

Depuis le Mac :

```bash
/Applications/Tailscale.app/Contents/MacOS/Tailscale status
/Applications/Tailscale.app/Contents/MacOS/Tailscale logout || true
/Applications/Tailscale.app/Contents/MacOS/Tailscale down || true
```

Puis :

```bash
sudo /Applications/Tailscale.app/Contents/MacOS/Tailscale up \
  --login-server=https://<HEADSCALE_PUBLIC_FQDN> \
  --auth-key=<PREAUTH_KEY> \
  --accept-dns=false \
  --accept-routes=false \
  --reset
```

Si la clé est valide et le `--login-server` accessible, tu dois voir :

```bash
/Applications/Tailscale.app/Contents/MacOS/Tailscale status
# 100.64.0.X  <MAC_HOSTNAME>  <USER>  macOS  -
```

---

## 9. Cas particulier : Home Assistant (add-on Tailscale)

### 9.1. Configurer l’add-on

Dans la configuration de l’add-on Tailscale (interface Home Assistant) :

```yaml
authkey: "<PREAUTH_KEY>"
hostname: "homeassistant"
login_server: "https://<HEADSCALE_PUBLIC_FQDN>"
userspace_networking: true  # ou false selon ton besoin
accept_dns: false
accept_routes: false
```

Ensuite, côté Headscale, tu verras un node :

```bash
headscale nodes list
# ...
# homeassistant | homeassistant | ... | 100.64.0.9, ...
```

Si l’expiration a été mise par erreur, tu peux la corriger :

```bash
headscale nodes expire --identifier <NODE_ID> --expiry 0001-01-01T00:00:00Z
```

> ⚠️ Attention : commande `expire` sert à **fixer** une date d’expiration.
> Pour ne pas expirer, il faut utiliser la valeur spéciale `0001-01-01T00:00:00Z`.

---

## 10. Android (smartphone & tablette)

### 10.1. Changer de serveur de login

Sur Android, il n’y a **pas (encore)** de bouton clair dans l’UI pour changer de `login-server` vers un Headscale custom.

La méthode fiable :

1. **Se déconnecter** de Tailscale sur l’app (logout).
2. **Effacer les données** de l’appli (ou désinstaller/réinstaller) pour repartir de zéro.
3. Lors du premier `tailscale up` par CLI dans Termux (si tu utilises Termux + binaire Linux), lancer :

   ```bash
   tailscale up \
     --login-server=https://<HEADSCALE_PUBLIC_FQDN> \
     --auth-key=<PREAUTH_KEY> \
     --accept-dns=false \
     --accept-routes=false \
     --reset
   ```
4. Côté Headscale, tu verras apparaître le nouveau node avec hostname (souvent `localhost` si tu utilises Termux) ; tu peux ensuite le renommer côté Headscale :

   ```bash
   headscale nodes rename --identifier <NODE_ID> <NOM_SOUHAITÉ>
   ```

> 💡 Attention : renommer dans Headscale ne change pas le hostname système Android/Termux, mais ça rend la liste Headscale plus lisible.

---

## 11. Vérifications globales

### 11.1. Depuis Headscale

```bash
headscale nodes list
```

Tu dois voir quelque chose du genre :

```text
ID | Hostname       | Name          | IP addresses                  | Connected | Expired
1  | jenkins        | jenkins       | 100.64.0.1, fd7a:115c:a1e0::1 | online    | no
2  | docker-ptr     | docker-ptr    | 100.64.0.2, fd7a:115c:a1e0::2 | online    | no
3  | nas            | nas           | 100.64.0.5, fd7a:115c:a1e0::5 | online    | no
...
```

### 11.2. Depuis un client (ex : PBS ou PVE)

```bash
tailscale status
```

Tu dois voir **tous** les peers (Mac, Android, HA, etc.) avec leurs IPs `100.64.0.X`.

---

## 12. Pièges rencontrés & leçons apprises

### 12.1. Mauvais port dans le reverse proxy

- **Symptôme :**
  - `curl http://127.0.0.1:8080` → 404 ou rien
  - Tailscale `up` semble bloquer ou ne jamais arriver à joindre le serveur
- **Cause :**
  - Caddy/nginx servait sur le port `80`, mais on essayait d’appeler `:8080` depuis l’extérieur.
- **Solution :**
  - Standardiser :
    - Headscale API : `:8080` (interne)
    - Reverse proxy : `:443` (public)
    - `--login-server=https://<HEADSCALE_PUBLIC_FQDN>` (pas de port explicite si 443)

### 12.2. Mélange Tailscale SaaS / Headscale

- **Symptôme :**
  - Le client Tailscale ouvre une URL `https://login.tailscale.com/...`
- **Cause :**
  - Pas de `--login-server` ou valeur incorrecte → le client repart sur le SaaS officiel.
- **Solution :**
  - Toujours vérifier la commande `tailscale up` :
    ```bash
    tailscale up --login-server=https://<HEADSCALE_PUBLIC_FQDN> ...
    ```

### 12.3. Expiration des nodes

- **Symptôme :**
  - Dans `headscale nodes list`, la colonne `Expired` passe à `yes`.
- **Cause :**
  - Mauvaise manipulation de la commande `expire` avec une date proche du présent.
- **Solution :**
  - Pour un node **qui ne doit pas expirer** :
    ```bash
    headscale nodes expire --identifier <ID> --expiry 0001-01-01T00:00:00Z
    ```

---

## 13. Résumé rapide (mode pense‑bête)

1. **Headscale**

   - Config dans `/etc/headscale/config.yaml`
   - `listen_addr: 0.0.0.0:8080`
   - `server_url: "https://<HEADSCALE_PUBLIC_FQDN>"`
2. **Reverse proxy**

   - Terminate TLS (Let’s Encrypt)
   - Proxy `/api` → `127.0.0.1:8080`
   - Servir la Web UI statique (`/var/www/headscale-admin`)
3. **Utilisateur & clés**

   - `headscale users create <USERNAME>`
   - `headscale preauthkeys create --user <ID> --reusable --ephemeral=false`
4. **Clients**

   - Commande type :
     ```bash
     tailscale logout || true
     tailscale down || true
     tailscale up \
       --login-server=https://<HEADSCALE_PUBLIC_FQDN> \
       --auth-key=<PREAUTH_KEY> \
       --accept-dns=false \
       --accept-routes=false \
       --reset
     ```
5. **Validation**

   - `headscale nodes list`
   - `tailscale status` depuis plusieurs machines

Avec cette checklist, tu peux **reconstruire tout ton tailnet Headscale** sans re‑te prendre 2 jours de galère, et tu peux publier ce README (après remplacement des placeholders) sur un dépôt public sans exposer ta vraie infra.