Info::pcShuffle: comment imiter Shuffle avec WireGuard

De wiki_pcwiki2
Aller à la navigationAller à la recherche

KEYWORDS: PCSSHUFFLE, SSHUFFLE, WIREGUARD, PCSSHUTLE.SH

Le 14/10/2026:

pcSshuffle

Version : 1.02

Date : 14 octobre 2026

Auteur : pcroad2gmail.com

Fonctionnement

pcSshuffle est la traduction en C++17 de pcSshutle.sh : une sortie « sshuttle-like » vers une cible distante. Chaque cible choisit son transport :

  • wireguard (defaut, comportement d'origine) : un netns
 (namespace reseau Linux) dedie contenant un tunnel WireGuard
 plein-tunnel, sans toucher au routage global de la machine. Chaque cible
 (srv18, ovh1, ovh2 par defaut)
 dispose de son propre netns, de sa propre interface WireGuard et de sa
 propre adresse IP privee.
  • wireguard-existing (nouveau, depuis la 1.02) : reutilise une
 interface WireGuard deja montee sur la machine (ex. wg1
 gere par wg-quick), sans la deplacer ni changer le routage
 global. up cree un netns dedie relie a l'hote par une paire
 veth (10.200.<vethId>.0/30), une table de routage
 51800+vethId (default dev <interface>), une
 regle ip rule from 10.200.<vethId>.0/30 (priorite 5100),
 un NAT (iptables MASQUERADE) et les regles FORWARD
 correspondantes. Les AllowedIPs du pair sont etendus a
 0.0.0.0/0 (wg set, sans effet sur les routes) ;
 la valeur d'origine est memorisee dans
 /run/pcSshuffle/<cible>.allowedips et restauree par
 down. Le serveur WireGuard distant doit router/NATer le
 trafic de l'adresse de l'interface locale (comme pour un client VPN).
  • headscale (depuis la 1.1) : reutilise un tailnet
 Tailscale/Headscale deja rejoint sur la machine (Headscale est le
 serveur de coordination auto-heberge ; le client qui tourne reellement
 est tailscale/tailscaled, pointe vers ce
 serveur). pcSshuffle ne gere ni l'authentification ni l'inscription du
 node : il se contente de verifier, via tailscale status --json,
 que la cible est un pair joignable et annonce comme exit-node, puis
 bascule tout le trafic de la machine vers lui (tailscale set
 --exit-node). Il n'y a pas de netns pour ce transport : voir
 « Pieges et limites connues » pour la difference d'ampleur avec le mode
 wireguard.

Par rapport au script bash d'origine, ce programme ajoute une detection et, quand c'est possible sans risque, une correction automatique de certaines erreurs de configuration :

Erreur detectee Comportement
Fichier de configuration JSON absent Cree automatiquement avec les valeurs par defaut (les 3 cibles du script
 d'origine), pour un fonctionnement immediat. Avertissement affiche.
Cible incoherente (champ manquant, adresse/cle/endpoint malformes,
 namespace ou interface reutilises par deux cibles)
Rejetee au chargement avec un message explicite nommant la cible et le
 champ en cause. Rien n'est corrige silencieusement ici : une valeur
 incoherente ne peut pas etre « devinee ».
Etat reseau partiel (netns laisse par une execution precedente
 interrompue : crash, Ctrl-C pendant up)
Detecte par status (« ETAT INCOHERENT ») et repare
 automatiquement par up : nettoyage complet puis remontee
 propre du tunnel.
Permissions trop larges sur une cle privee WireGuard Corrigees automatiquement en 600, avec avertissement. Une cle absente ou
 de contenu invalide n'est en revanche jamais corrigee (il faudrait
 inventer une cle, ce qui casserait la confiance avec le pair distant) :
 le programme s'arrete avec un message explicite.
Variable DISPLAY absente pour l'action firefox
 (transport wireguard)
Le script bash d'origine plante (« unbound variable », set -u)
 dans ce cas. pcSshuffle utilise une valeur de repli (:0) avec
 un avertissement, au lieu d'un arret brutal.
DISPLAY obsolete pour l'action firefox (ex.
 session ssh -X deja fermee, variable restee exportee dans
 le shell)
Detecte avant de lancer firefox : si
 /tmp/.X11-unix/X<numero> n'existe pas pour le
 DISPLAY resolu, pcSshuffle s'arrete avec un message nommant
 le socket attendu, au lieu de laisser afficher l'erreur X11 opaque
 cannot open display.
Pair Headscale absent du tailnet, hors ligne, ou non annonce comme
 exit-node (transport headscale)
Rejete par status/up avec un message explicite
 nommant la cause exacte. Aucune tentative « a l'aveugle » de
 tailscale set --exit-node sur un pair non verifie.

Detection de l'etat d'un tunnel

Un tunnel est considere comme :

  • DOWN : le netns n'existe pas.
  • UP : le netns existe et l'interface WireGuard, son adresse
 IPv4, sa route par defaut et son /etc/netns/<ns>/resolv.conf
 sont tous presents.
  • ETAT INCOHERENT : le netns existe mais au moins un des quatre
 elements ci-dessus manque. C'est le cas typique d'une execution
 precedente de up interrompue avant la fin.

status affiche cet etat en detail ; up le detecte et repare automatiquement (appel implicite de down puis remontee complete) avant de continuer.

Fichier de configuration

Chemin par defaut : /etc/pcSshuffle/config.json (modifiable avec -c/--config).

{
    "keyDir": "/etc/wireguard/keys",
    "dns": "9.9.9.9",
    "targets": {
        "srv18": {
            "namespace": "ns-srv18",
            "interface": "wgff",
            "address": "10.0.3.20/32",
            "peerPublicKey": "BPBurdxfynCJtK6yh4fVlD6zF+rH03ZE7QQuqulQlSs=",
            "endpoint": "82.67.120.130:51823"
        },
        "ovh1x": {
            "transport": "wireguard-existing",
            "namespace": "ns-ovh1x",
            "interface": "wg1"
        },
        "srv18ts": {
            "transport": "headscale",
            "exitNode": "srv18"
        }
    }
}
Champ Role
keyDir (global, optionnel) Repertoire des cles privees WireGuard. Chaque cible wireguard
 utilise <keyDir>/<interface>.key. Defaut :
 /etc/wireguard/keys. Sans effet sur les cibles
 headscale.
dns (global, optionnel) Serveur DNS ecrit dans le resolv.conf du netns d'une cible
 wireguard. Defaut : 9.9.9.9. Sans effet sur les
 cibles headscale.
targets.<nom>.transport (optionnel) "wireguard" (defaut), "wireguard-existing" ou
 "headscale". Determine
 les champs requis ci-dessous.
targets.<nom>.namespace (wireguard) Nom du netns Linux dedie a cette cible (doit etre unique parmi les
 cibles wireguard).
targets.<nom>.interface (wireguard) Nom de l'interface WireGuard (doit etre unique parmi les cibles
 wireguard ; determine aussi le nom du fichier de cle,
 <interface>.key).
targets.<nom>.address (wireguard) Adresse IPv4/CIDR de l'interface dans le netns (ex. 10.0.3.20/32).
targets.<nom>.peerPublicKey (wireguard) Cle publique WireGuard du serveur distant.
targets.<nom>.endpoint (wireguard) host:port du serveur WireGuard distant.
targets.<nom>.namespace, interface (wireguard-existing) Netns dedie (unique) et interface WireGuard existante sur l'hote
 (unique, a monter avant : wg-quick up wg1).
targets.<nom>.peerPublicKey (wireguard-existing, optionnel) Pair a utiliser ; obligatoire si l'interface a plusieurs pairs.
targets.<nom>.vethId (wireguard-existing, optionnel) Entier 1-254 (defaut 1, unique par cible) : sous-reseau
 10.200.<vethId>.0/30, table 51800+vethId, veth
 pcs<vethId>h/pcs<vethId>n.
targets.<nom>.exitNode (headscale) HostName Tailscale du pair a utiliser comme exit-node (tel
 qu'affiche par tailscale status, ex. srv18).
 Doit etre annonce cote de ce pair avec tailscale up
 --advertise-exit-node.

La cle privee WireGuard n'est jamais stockee dans ce fichier JSON (qui reste en permissions 644, non secret) : elle vit dans un fichier separe sous keyDir, comme dans le script d'origine. Une cible headscale ne stocke aucun secret : l'authentification Tailscale/Headscale est geree en dehors de pcSshuffle.

Syntaxe

pcSshuffle [-c chemin] <cible> [action] [arguments...]
pcSshuffle -h|--help

Options

Option Description Exemple
-h, --help Affiche l'aide et quitte. pcSshuffle --help
-c, --config <chemin> Fichier de configuration JSON. Cree automatiquement avec des valeurs par
 defaut s'il n'existe pas. Defaut : /etc/pcSshuffle/config.json
pcSshuffle -c /etc/pcSshuffle/perso.json srv18 status

Actions

Action Description Exemple
status wireguard et wireguard-existing : DOWN / UP (avec
 wg show) / ETAT INCOHERENT (detail des elements manquants
 pour wireguard-existing ; ERREUR si l'interface n'existe pas). headscale : DOWN/UP selon que le pair est l'exit-node
 actif, plus son etat en ligne et son statut d'exit-node annonce.
pcSshuffle srv18 status
up wireguard : monte le tunnel (idempotent, autoreparateur).
 wireguard-existing : cree netns + veth + ip rule + NAT
 vers l'interface existante et etend les AllowedIPs du pair ; passe
 rp_filter strict a 2 ; idempotent, autoreparateur.
 headscale : bascule tout le trafic de la machine vers ce
 pair (tailscale set --exit-node), idempotent si deja actif.
pcSshuffle srv18 up
down wireguard : coupe le tunnel et supprime le netns.
 wireguard-existing : retire netns, veth, regle, NAT et restaure les
 AllowedIPs ; l'interface existante reste montee. headscale :
 desactive l'exit-node, seulement s'il s'agit encore de celui de cette
 cible.
pcSshuffle ovh2 down
ip Monte le tunnel si besoin puis affiche l'IP publique de sortie
 (curl https://ifconfig.me, dans le netns pour une cible
 wireguard ou wireguard-existing, directement sur l'hote pour une cible headscale).
pcSshuffle srv18 ip
firefox [arguments...] Lance firefox (profil <cible>-exit) a travers le
 tunnel wireguard, ou directement sur l'hote pour une cible headscale (le
 routage exit-node deja actif s'applique de toute facon).
pcSshuffle ovh1 firefox https://ifconfig.me
[--] commande [arguments...] Execute la commande dans le netns (wireguard) ou directement sur l'hote
 (headscale). Le -- est optionnel ; il permet de lancer une
 commande dont le nom coincide avec une action ci-dessus (ex. un script
 nomme status ou up) -- ce que le script bash
 d'origine documentait dans son usage sans jamais l'implementer reellement.
pcSshuffle ovh1 curl -s https://ifconfig.me
 pcSshuffle ovh1 -- status
(aucune action) Ouvre un shell interactif (bash -l), dans le netns
 (wireguard) ou directement sur l'hote (headscale).
pcSshuffle srv18

Codes de retour

Code Signification
0 Action terminee avec succes.
1 Echec d'une commande sous-jacente (ip, wg, curl...), cible inconnue,
      ou erreur de configuration.
2 Erreur de ligne de commande (cible manquante, option invalide).

Exemples : sortie via ovh1 (wireguard-existing)

Cible dans /etc/pcSshuffle/config.json :

"ovh1": {
    "transport": "wireguard-existing",
    "namespace": "ns-ovh1",
    "interface": "wg1"
}
pcSshuffle ovh1 up
pcSshuffle ovh1 ip          # affiche l'IP d'ovh1
pcSshuffle ovh1 status
pcSshuffle ovh1 curl -s https://ifconfig.me
pcSshuffle ovh1 firefox https://ifconfig.me
pcSshuffle ovh1 down

Utiliser l'action firefox (profil dedie ovh1-exit, --no-remote) et non firefox-esr : ce dernier se raccroche a un Firefox deja ouvert, hors du netns, et affiche l'IP locale. Creer le profil une fois : firefox-esr -CreateProfile ovh1-exit.

Alias dans ~/.bashrc :

alias firefoxOvh1='pcSshuffle ovh1 firefox'
firefoxOvh1 https://ifconfig.me

Compilation

Paquets Debian requis :

apt install g++ cmake nlohmann-json3-dev iproute2 iptables wireguard-tools curl firefox-esr

Pour le transport headscale, le paquet tailscale (depot officiel Tailscale, pas dans Debian) doit egalement etre installe et la machine deja inscrite sur le tailnet -- voir « Prerequis d'execution ».

Build :

mkdir -p build && cd build && cmake .. && make

Le binaire pcSshuffle est genere dans build/. A la toute premiere compilation dans un repertoire de build donne, le programme pcShowDir est automatiquement invoque.

Installation dans /home/local/bin :

cmake --install build

Pourquoi pas Boost.Asio : ce programme ne fait aucune entree/sortie reseau directe en C++. Toute la mecanique reseau (creation du netns, interface WireGuard, routage, resolution DNS, requete HTTP de pcSshuffle ip) est deleguee aux outils systeme deja utilises par le script d'origine (ip, wg, curl), via fork()/execvp() (voir ClassProcessRunner), exactement comme le ferait un script shell. Reimplementer la configuration WireGuard ou la gestion des netns par appels systeme bas niveau (netlink, setns()...) aurait ajoute une complexite et un risque significatifs sans benefice reel, l'outillage systeme faisant deja ce travail de facon fiable.

Prerequis d'execution

  • root obligatoire : creation de netns et d'interfaces WireGuard
 (CAP_SYS_ADMIN/CAP_NET_ADMIN) ; tailscale
 set requiert egalement root ou le groupe operateur Tailscale.
  • Transport wireguard : les cles privees ne sont jamais
 generees automatiquement : wg genkey >
 /etc/wireguard/keys/<interface>.key puis transmettre la cle
 publique correspondante (wg pubkey <
 /etc/wireguard/keys/<interface>.key) au pair distant.
  • Transport wireguard-existing : l'interface WireGuard doit deja etre
 montee (wg-quick up wg1) ; wg, ip
 et iptables (paquets wireguard-tools,
 iproute2, iptables) ; le serveur distant doit
 router/NATer le trafic. Pour firefox, creer le profil une
 fois : firefox-esr -CreateProfile <cible>-exit.
  • Transport headscale : la machine doit deja avoir rejoint le
 tailnet (tailscale up --login-server=https://votre-headscale/,
 a faire une seule fois, hors de pcSshuffle) et le pair cible doit
 s'annoncer comme exit-node (tailscale up
 --advertise-exit-node sur ce pair, puis approbation cote
 Headscale si la route par defaut n'est pas auto-approuvee :
 headscale nodes list-routes / headscale routes
 enable).

Pieges et limites connues

  • wireguard-existing : effets de bord sur l'hote : up
 active net.ipv4.ip_forward s'il est a 0 (non restaure),
 ajoute des regles iptables (nat/FORWARD) et modifie les
 AllowedIPs du pair de l'interface existante (restaures par
 down ; si l'etat memorise dans /run/pcSshuffle
 est perdu, par exemple apres un redemarrage, ils restent etendus
 jusqu'au prochain wg-quick down/up). Un rp_filter
 strict (1) sur all ou sur l'interface est passe
 automatiquement a 2 (loose) avec un avertissement ; cette valeur n'est
 pas restauree par down.
  • wireguard-existing : prerequis distant : le serveur WireGuard doit
 accepter le trafic de l'adresse de l'interface locale (ex.
 10.0.1.18) et le router avec NAT vers Internet. Sans cela,
 up reussit mais ip expire.
  • Aucun test de handshake (wireguard) : comme le script d'origine,
 up configure le tunnel et ajoute la route sans attendre ni
 verifier qu'une poignee de main WireGuard a reussi. status
 (wg show) affiche latest handshake une fois le
 trafic passe, jamais avant.
  • firefox (wireguard) requiert une session X11
 accessible par socket Unix (/tmp/.X11-unix) : un
 DISPLAY de la forme hote:N.M (ssh
 -X distant, sans serveur X local) ne fonctionnera pas depuis le
 netns, la pile reseau y etant isolee.
  • DISPLAY obsolete (rencontre en usage reel) : un shell
 root de longue duree peut garder un DISPLAY exporte par une
 session ssh -X depuis longtemps refermee (ex.
 localhost:12.0 alors que la seule session graphique active
 est :0). pcSshuffle verifie desormais que
 /tmp/.X11-unix/X<numero> existe avant de lancer
 firefox et s'arrete avec un message explicite si ce n'est pas le cas,
 au lieu de laisser afficher l'erreur X11 opaque cannot open
 display. Solution : echo $DISPLAY +
 ls /tmp/.X11-unix/ pour identifier la session reellement
 active, puis corriger DISPLAY dans ce shell.
  • Correction des permissions de cle (wireguard) : seules les
 permissions sont corrigees automatiquement (600). Une cle absente ou
 visiblement invalide (longueur/format incorrect) n'est jamais corrigee
 ni regeneree.
  • Ampleur tres differente du transport headscale : contrairement au
 mode wireguard (isole dans un netns : seules les commandes lancees via
 pcSshuffle sont concernees), up en mode headscale change le
 routage par defaut de toute la machine
 (tailscale set --exit-node) jusqu'a down ou une
 intervention manuelle. Si cette machine est administree a distance via
 sa route par defaut habituelle (et non via le tailnet lui-meme), cette
 route sera elle aussi redirigee -- pcSshuffle affiche un avertissement
 avant d'activer l'exit-node, mais ne peut pas detecter ce risque a
 l'avance.
  • down en mode headscale est prudent par construction :
 il ne desactive l'exit-node que si le pair actif est bien celui de la
 cible, pour ne jamais defaire une configuration tailscale
 --exit-node etablie manuellement ou par une autre cible.