Info::pcShuffle: comment imiter Shuffle avec WireGuard
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,ovh2par 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.wg1gere parwg-quick), sans la deplacer ni changer le routage global.upcree un netns dedie relie a l'hote par une paire veth (10.200.<vethId>.0/30), une table de routage51800+vethId(default dev <interface>), une regleip rule from 10.200.<vethId>.0/30(priorite 5100), un NAT (iptables MASQUERADE) et les reglesFORWARDcorrespondantes. LesAllowedIPsdu pair sont etendus a0.0.0.0/0(wg set, sans effet sur les routes) ; la valeur d'origine est memorisee dans/run/pcSshuffle/<cible>.allowedipset restauree pardown. 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 esttailscale/tailscaled, pointe vers ce serveur). pcSshuffle ne gere ni l'authentification ni l'inscription du node : il se contente de verifier, viatailscale 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, |
Detecte par status (« ETAT INCOHERENT ») et repare
automatiquement par
|
| 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 (
|
DISPLAY obsolete pour l'action firefox (ex.
session
|
Detecte avant de lancer firefox : si
|
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
|
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 |
dns (global, optionnel)
|
Serveur DNS ecrit dans le resolv.conf du netns d'une cible
|
targets.<nom>.transport (optionnel)
|
"wireguard" (defaut), "wireguard-existing" ou
|
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,
|
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 :
|
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
|
targets.<nom>.exitNode (headscale)
|
HostName Tailscale du pair a utiliser comme exit-node (tel
qu'affiche par |
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 :
|
pcSshuffle -c /etc/pcSshuffle/perso.json srv18 status
|
Actions
| Action | Description | Exemple |
|---|---|---|
status
|
wireguard et wireguard-existing : DOWN / UP (avec
|
pcSshuffle srv18 status
|
up
|
wireguard : monte le tunnel (idempotent, autoreparateur).
wireguard-existing : cree netns + veth + |
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
(
|
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 |
pcSshuffle ovh1 curl -s https://ifconfig.me
|
| (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 setrequiert egalement root ou le groupe operateur Tailscale.
- Transport wireguard : les cles privees ne sont jamais
generees automatiquement :wg genkey > /etc/wireguard/keys/<interface>.keypuis 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,ipetiptables(paquetswireguard-tools,iproute2,iptables) ; le serveur distant doit router/NATer le trafic. Pourfirefox, 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-nodesur 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
activenet.ipv4.ip_forwards'il est a 0 (non restaure), ajoute des regles iptables (nat/FORWARD) et modifie lesAllowedIPsdu pair de l'interface existante (restaures pardown; si l'etat memorise dans/run/pcSshuffleest perdu, par exemple apres un redemarrage, ils restent etendus jusqu'au prochainwg-quick down/up). Unrp_filterstrict (1) surallou sur l'interface est passe automatiquement a 2 (loose) avec un avertissement ; cette valeur n'est pas restauree pardown.
- 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,upreussit maisipexpire.
- Aucun test de handshake (wireguard) : comme le script d'origine,
upconfigure le tunnel et ajoute la route sans attendre ni verifier qu'une poignee de main WireGuard a reussi.status(wg show) affichelatest handshakeune fois le trafic passe, jamais avant.
firefox(wireguard) requiert une session X11
accessible par socket Unix (/tmp/.X11-unix) : unDISPLAYde la formehote:N.M(ssh -Xdistant, sans serveur X local) ne fonctionnera pas depuis le netns, la pile reseau y etant isolee.
DISPLAYobsolete (rencontre en usage reel) : un shell
root de longue duree peut garder unDISPLAYexporte par une sessionssh -Xdepuis longtemps refermee (ex.localhost:12.0alors 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 opaquecannot open display. Solution :echo $DISPLAY+ls /tmp/.X11-unix/pour identifier la session reellement active, puis corrigerDISPLAYdans 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),upen mode headscale change le routage par defaut de toute la machine (tailscale set --exit-node) jusqu'adownou 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.
downen 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.