↓ Aller au contenu
Cryptolab
Cryptolab

Pangolin : installation, accès Zero Trust et maintenance

·2588 mots·13 mins
Infrastructure Infra Réseau Sécurité Self-Hosting Pangolin
Foudreclair
Auteur
Foudreclair
Cryptolab est un blog personnel où je documente mes expérimentations techniques : infra, self-hosting, réseau, crypto et projets parfois inutiles, souvent instructifs.
Sommaire

Pourquoi Pangolin ?
#

Quand on commence à auto-héberger sérieusement, on connaît tous la dérive :

  • un port ouvert “temporairement”, puis un second,
  • un reverse proxy exposé “juste pour tester”,
  • et au final une infra qu’on n’ose plus trop regarder.

Pangolin est arrivé pile à ce moment-là pour moi.
Pas comme une solution miracle, mais comme un moyen de remettre de l’ordre.

Des solutions comme Cloudflare Tunnel peuvent aider, mais elles imposent :

  • un passage par une infrastructure tierce
  • une dépendance à un écosystème propriétaire
  • un modèle Zero Trust peu maîtrisé côté infrastructure

Pangolin répond à ce problème autrement.

Pangolin est une plateforme open-source d’accès distant, basée sur l’identité, construite au-dessus de WireGuard.
Elle combine deux approches dans un même outil :

  • un reverse proxy pour l’accès aux applications web
  • un accès de type VPN pour les ressources privées (SSH, bases de données, services internes)

Les réseaux privés sont reliés à Pangolin via des connecteurs légers appelés sites.
Un site établit un tunnel sécurisé sans IP publique ni ouverture de ports, et permet d’exposer uniquement des ressources précises, jamais un réseau entier.

Site officiel : https://pangolin.net
Dépôt GitHub : https://github.com/fosrl/pangolin

Architecture Pangolin

Positionnement clair : Pangolin, Cloudflare et VPN
#

Pangolin n’est pas un VPN de remplacement. Un VPN reste recommandé pour l’administration bas niveau et les accès de secours.

Pangolin apporte :

  • un reverse proxy Zero Trust
  • un contrôle d’accès applicatif
  • une segmentation fine des ressources

Cet article documente l’installation complète de Pangolin, sa mise à jour, ainsi que la création de ressources publiques et privées, avec l’ajout d’un node Newt côté réseau cible.

Ce n’est pas une réécriture de la documentation officielle.
C’est un retour d’expérience, basé sur une utilisation réelle.

Prérequis
#

  • VPS Linux avec IP publique
  • Nom de domaine pointant vers le VPS (ex : pangolin.example.com)
  • Docker et Docker Compose installés
  • Ports ouverts :
    • 80 / TCP
    • 443 / TCP
    • 51820 / UDP
    • 21820 / UDP
  • Adresse email valide pour Let’s Encrypt

Installation de Pangolin
#

J’ai personnelement utilisé le quick install script : https://docs.pangolin.net/self-host/quick-install

Cette méthode :

  • installe automatiquement les services nécessaires
  • configure HTTPS
  • initialise le dashboard Pangolin

Pour l’éxécuter, rien de plus simple :

curl -fsSL https://static.pangolin.net/get-installer.sh | bash

Ensuite on lui donne les droits d’éxécution :

chmod +x installer

On éxécute l’installateur :

./installer

Configuration des paramètres de base
#

Lors de l’installation, le script vous demande de renseigner plusieurs paramètres essentiels :

  • Base Domain
    Entrez votre nom de domaine racine, sans sous-domaine
    (ex. example.com)

  • Dashboard Domain
    Appuyez sur Entrée pour accepter la valeur par défaut
    (ex. pangolin.example.com)
    ou indiquez un domaine personnalisé.

  • Adresse email Let’s Encrypt
    Fournissez une adresse email valide utilisée pour :

    • la génération des certificats SSL
    • la création du compte administrateur

  • Tunneling (Gerbil)
    Choisissez si vous souhaitez installer Gerbil pour activer les connexions tunnelisées :

    • Oui (par défaut, recommandé) : Pangolin fonctionne en mode tunnel Zero Trust
    • Non : Pangolin fonctionne comme un reverse proxy classique, sans tunneling

Options non obligatoires
#

Configuration des emails (SMTP)
#

La gestion des emails est optionnelle et peut être configurée ultérieurement.

Lors de l’installation, le script vous demande si vous souhaitez activer l’envoi d’emails via SMTP :

  • Valeur par défaut : Non (recommandé pour une première installation)
  • Si activé, vous devrez fournir les informations de votre serveur SMTP :
    • hôte
    • port
    • nom d’utilisateur
    • mot de passe

Installation de CrowdSec
#

Le script propose également l’installation de CrowdSec pour renforcer la sécurité :

  • Valeur par défaut : Non (recommandé au départ)
  • Si activé, vous confirmez que vous êtes prêt à :
    • gérer la configuration CrowdSec
    • maintenir les règles et décisions associées

👉 CrowdSec peut être ajouté plus tard, une fois Pangolin correctement opérationnel.

Accéder au dashboard
#

À la fin de l’installation, le script affiche l’URL du dashboard.
Rendez-vous à l’adresse suivante : https://pangolin.example.com/auth/initial-setup

Dashboard Pangolin

Vue d’ensemble du dashboard Pangolin après l’installation.

Le dashboard doit se charger avec un certificat SSL configuré automatiquement.
⚠️ La validation du premier certificat peut prendre quelques minutes : un avertissement de sécurité temporaire dans le navigateur est normal.

Création du compte administrateur
#

Complétez la configuration initiale du compte administrateur :

  • saisissez votre adresse email administrateur
  • définissez un mot de passe fort
  • vérifiez votre email (si la configuration SMTP est activée)

👉 Utilisez un mot de passe unique et robuste : ce compte dispose de l’ensemble des droits système.Après la création je recommande l’utilisation d’une 2FA.

Création de la première organisation
#

Une fois connecté au dashboard :

  • renseignez le nom de l’organisation
  • ajoutez une description
  • cliquez sur Create Organization

L’organisation sert de conteneur logique pour :

  • les utilisateurs
  • les sites
  • les ressources
  • les règles d’accès

À ce stade, Pangolin est fonctionnel, mais il ne fait encore rien d’utile. C’est normal : toute la puissance arrive avec les sites, les nodes et les ressources.

Installation d’un node
#

Pour que pangolin accède à votre réseau il faut installer un node sur votre réseau local. Il y trois solutions pour installer un node :

  • Site Newt (recommandé solution par Pangolin)
  • Wireguard
  • Local (sans tunnel)

J’ai utilisé de mon côté Newt.

Pour l’installer, j’ai choisi docker mais on peut passer par les packages disponible ou kubernetes / podman.

Installation du node via le docker-compose.yml
#

services:
  newt:
    image: fosrl/newt
    container_name: newt
    restart: unless-stopped
    environment:
      - PANGOLIN_ENDPOINT=${PANGOLIN_ENDPOINT}
      - NEWT_ID=${NEWT_ID}
      - NEWT_SECRET=${NEWT_SECRET}

.env (ne jamais commit)
#

PANGOLIN_ENDPOINT=https://pangolin.example.com
NEWT_ID=changeme
NEWT_SECRET=changeme

Démarrage :

docker compose up -d
docker logs -f newt

À partir de là, Pangolin commence vraiment à devenir intéressant : le réseau est joint, sans port ouvert, et sans configuration réseau exotique.

Création d’une ressource
#

Une ressource représente un service que l’on souhaite exposer ou rendre accessible via Pangolin.

Il existe deux types de ressources :

  • Ressource publique : exposée sur Internet
  • Ressource privée : accessible uniquement aux utilisateurs connectés au client Pangolin.

Ressource publique : exposition applicative
#

Une ressource publique fonctionne comme un reverse proxy.

On définit :

  • un domaine
  • une ou plusieurs cibles (protocole + adresse + port)
  • des options de sécurité et de routage

Il est possible de configurer plusieurs cibles pour une même ressource.
L’intérêt est de pouvoir :

  • répartir la charge entre plusieurs serveurs ou sites
  • assurer une continuité de service en cas de panne

Pangolin permet également d’activer l’authentification sur une ressource publique.
Dans ce cas, l’utilisateur doit d’abord se connecter au portail Pangolin (SSO) avant d’accéder à l’application.

Ressource privée : accès interne sécurisé
#

Une ressource privée permet d’accéder à un service sans aucune exposition publique.

On définit :

  • une cible (adresse interne)
  • un ou plusieurs ports
  • les utilisateurs autorisés

Il est possible de définir un alias afin de faciliter l’accès à la ressource.

👉 Ce type de ressource est idéal pour :

  • SSH
  • bases de données
  • dashboards internes
  • outils d’administration

Aucun port public n’est ouvert.

Création d’une ressource publique
#

Une ressource publique permet d’exposer une application via HTTPS, en s’appuyant sur Pangolin comme reverse proxy sécurisé. Si vous avez déjà exposé un service avec Nginx Proxy Manager ou Caddy, vous ne serez pas dépaysé — la différence, c’est le contrôle d’accès.

Lors de la création d’une ressource publique, plusieurs paramètres sont à renseigner.

Informations sur la ressource
#

  • Type

    • Ressource HTTPS : proxy HTTP/HTTPS basé sur un nom de domaine
    • Ressource TCP/UDP brute : proxy TCP ou UDP basé sur un port
      (dans le cas d’une exposition web classique, on choisit Ressource HTTPS)

  • Nom
    Nom d’affichage de la ressource dans le dashboard Pangolin.

Paramètres HTTPS
#

  • Sous-domaine
    Sous-domaine à exposer (ex. gitea)

  • Domaine de base
    Domaine racine sélectionné lors de l’installation
    (ex. cryptolab.re)

➡️ L’URL finale sera par exemple :
https://gitea.cryptolab.re

Configuration des cibles
#

Une ou plusieurs cibles peuvent être définies pour acheminer le trafic vers les services backend.

Pour chaque cible, on configure :

  • Nœud Pangolin
    Node par lequel le trafic est routé (ex. gitea)

  • Protocole
    Généralement http ou https

  • Adresse (Host)
    Adresse interne du service
    (ex. 192.168.1.50)

  • Port
    Port du service backend
    (ex. 3000)

Il est possible d’ajouter plusieurs cibles afin de :

  • répartir la charge
  • assurer une haute disponibilité

Vérification de l’état de santé (Healthcheck)
#

Pangolin permet d’activer une vérification de l’état de santé sur chaque cible :

  • port de vérification configurable
  • intervalle personnalisable
  • statut visible dans le dashboard

👉 Le healthcheck est fortement recommandé lorsqu’il y a plusieurs cibles, afin d’éviter d’envoyer du trafic vers un service indisponible.

Sécurité et accès
#

  • Les ressources publiques peuvent être protégées par l’authentification Pangolin
  • L’utilisateur devra alors se connecter via le portail Pangolin (SSO) avant d’accéder à l’application

Par défaut :

  • le SSL est activé
  • un certificat Let’s Encrypt est généré automatiquement
  • aucun certificat n’est à gérer manuellement

Exemple
#

  • URL exposée : https://gitea.cryptolab.re
  • Cible :
    • Nœud : gitea
    • Adresse : 192.168.1.50
    • Port : 3000
  • Healthcheck : activé
  • Authentification Pangolin : optionnelle

Ressource publique Pangolin

Exemple de ressource HTTPS avec plusieurs cibles et healthcheck.

Création d’une ressource privée
#

Une ressource privée permet de donner accès à un service interne sans aucune exposition publique.
Elle est uniquement accessible aux utilisateurs authentifiés via Pangolin.

Lors de la création d’une ressource privée, on définit :

  • Nom : nom explicite de la ressource
  • Nœud : node Pangolin par lequel le réseau est joint
  • Destination : adresse interne de la cible
    (nom d’hôte, adresse IP ou plage CIDR selon le mode choisi)
  • Alias (optionnel) : nom DNS interne pour simplifier l’accès
  • Restrictions de ports :
    • TCP : ports autorisés ou tous
    • UDP : ports autorisés ou tous
    • ICMP : autorisé ou non

Exemple de configuration
#

  • Type : TCP
  • Destination : 192.168.1.10
  • Port autorisé : 22
  • Alias : monserveur.lan
  • Accès : réservé aux utilisateurs authentifiés dans l’organisation

👉 Aucun port public n’est exposé sur Internet.

Ressource privée Pangolin

Ressource TCP privée exposant un accès SSH sans port public.

Accès à une ressource privée
#

Pour accéder aux ressources privées, il est nécessaire d’installer le client Pangolin sur le poste utilisateur.

Téléchargement du client officiel :
👉 https://pangolin.net/downloads

Étapes côté client
#

  1. Télécharger et installer le client Pangolin
    Utilisez l’installeur officiel (.msi sous Windows, ou équivalent selon l’OS).

  2. Lancer Pangolin
    Ouvrez l’application depuis le menu Démarrer ou le raccourci bureau.

  3. Se connecter à votre instance Pangolin

    • Connectez-vous à votre instance Pangolin auto-hébergée
    • Cliquez sur l’icône Pangolin dans la barre système
    • Sélectionnez Log in

Vous devriez avoir ça sur votre client.

Client
Une fois connecté, les ressources privées définies dans l’organisation deviennent accessibles de manière sécurisée. Par exemple taper dans votre navigateur : http://serveur.lan vous pourrez accéder à votre ressource privée via votre alias. C’est généralement à ce moment-là qu’on se dit : “OK, là je vois l’intérêt.”

Mise à jour de Pangolin
#

Documentation officielle :
https://docs.pangolin.net/self-host/how-to-update#how-to-update

Avant de mettre à jour
#

Avant toute mise à jour, il est fortement recommandé de :

  • sauvegarder les données
  • copier le répertoire de configuration dans un emplacement sûr
  • s’assurer de pouvoir revenir en arrière en cas de problème

👉 Bonne pratique :
Mettre à jour progressivement entre les versions majeures.
Par exemple :

  • ✅ 1.0.0 → 1.1.0 → 1.2.0
  • ❌ 1.0.0 → 1.2.0 directement

Si vous avez déjà cassé un reverse proxy à cause d’un docker compose pull un peu trop rapide, vous savez pourquoi cette section existe.

Procédure de mise à jour
#

1️⃣ Arrêter la stack
#

Commencez par arrêter tous les conteneurs Pangolin :

sudo docker compose down

2️⃣ Vérifier les dernières versions disponibles
#

Avant toute mise à jour, identifiez les dernières versions stables des composants utilisés par Pangolin.
Évitez les versions pre-release ou beta en environnement de production.

Sources recommandées :

Notez précisément les numéros de version afin de les reporter dans les fichiers de configuration.

3️⃣ Mettre à jour les numéros de version
#

Éditez le fichier docker-compose.yml et mettez à jour les images Docker concernées.

services:
  pangolin:
    image: fosrl/pangolin:ee-1.14.1
    # ... reste de la configuration

  gerbil:
    image: fosrl/gerbil:1.3.0
    # ... reste de la configuration

  traefik:
    image: traefik:v3.6.5
    # ... reste de la configuration

👉 Vous pouvez :

  • mettre à jour un service à la fois afin de limiter les risques
  • ou l’ensemble de la stack en une seule opération, selon votre tolérance au risque

4️⃣ Mettre à jour le plugin Badger (Traefik)
#

Si le plugin Badger est utilisé par Traefik, sa version doit également être mise à jour.

Dans le fichier config/traefik/traefik_config.yml :

experimental:
  plugins:
    badger:
      moduleName: github.com/fosrl/badger
      version: v1.3.0

5️⃣ Télécharger les nouvelles images
#

Une fois les numéros de version mis à jour dans les fichiers de configuration, téléchargez les nouvelles images Docker :

sudo docker compose pull

6️⃣ Redémarrer la stack Pangolin
#

Relancez la stack avec les nouvelles versions :

sudo docker compose up -d

Les migrations nécessaires (base de données, configuration) sont exécutées automatiquement si besoin.

7️⃣ Surveiller le démarrage
#

Surveillez les logs afin de vérifier que tous les services démarrent correctement :

sudo docker compose logs -f

Soyez attentif notamment :

  • aux messages de migration

  • à l’état des connexions Gerbil

  • aux logs Traefik et Badger

8️⃣ Vérifier le bon fonctionnement
#

Une fois la stack opérationnelle, vérifiez systématiquement :

  • l’accès au dashboard Pangolin
  • l’accès aux ressources publiques
  • l’accès aux ressources privées

Mise à jour automatisée avec Ansible
#

Pour fiabiliser et standardiser les mises à jour, j’ai écrit un rôle Ansible dédié permettant de mettre à jour Pangolin et tout son écosystème de manière reproductible.

👉 Lien vers le Dépôt Github

Principe
#

Le rôle applique une stratégie volontairement simple et assumée :

arrêt → mise à jour → redémarrage → nettoyage

⚠️ Cette approche implique un court downtime, accepté et maîtrisé sur un VPS dédié Pangolin.

Composants gérés
#

Le rôle met à jour l’ensemble de la stack :

  • Pangolin
  • Gerbil
  • Traefik
  • Badger (plugin Traefik)
  • CrowdSec Traefik Bouncer (si utilisé)

Fonctionnement
#

Concrètement, le rôle Ansible :

  1. arrête proprement la stack Pangolin
  2. met à jour les fichiers de configuration via des templates Jinja2
  3. télécharge les nouvelles images Docker
  4. redémarre la stack
  5. nettoie les images Docker inutilisées

Les versions sont pilotées par variables, ce qui permet :

  • un contrôle précis des upgrades
  • une traçabilité claire
  • un rollback simple via Git

Exécution
#

La mise à jour se lance via un playbook dédié :

ansible-playbook -i inventory/prod.ini playbook-pangolin-upgrade.yml

Licence Pangolin
#

Certaines fonctionnalités avancées de Pangolin nécessitent une licence (par exemple des options liées à l’authentification, à l’access control ou à des usages plus avancés).

Bonne nouvelle :
👉 une licence gratuite est disponible pour un usage personnel.

Licence gratuite (usage particulier)
#

Pour un usage homelab / personnel, il suffit de :

  1. créer un compte Pangolin
  2. activer la licence gratuite associée

Lien officiel :
Pangolin – Création de compte et licences

Cette licence gratuite est largement suffisante pour :

  • un homelab
  • un VPS personnel
  • des projets non commerciaux

Conclusion
#

Pangolin ne fait pas de magie, mais il fait exactement ce qu’on lui demande :
exposer des services proprement, sans ouvrir son réseau dans tous les sens, et sans déléguer sa sécurité à un tiers.

Une fois en place sur un VPS, avec des agents Newt côté réseaux privés, on se rend vite compte que :

  • on ouvre moins de ports
  • on comprend mieux ce qui est exposé
  • on dort un peu plus tranquille

Ce guide est le reflet d’une utilisation réelle, avec ses choix assumés :

  • un VPN conservé pour l’admin bas niveau
  • des mises à jour maîtrisées
  • un peu d’automatisation Ansible pour éviter les boulettes à 23h

Si vous avez un homelab un peu sérieux et que vous en avez marre des bricolages autour du reverse proxy, Pangolin mérite clairement un test.

Articles connexes