SSH Session Resilience (tmux + Mosh)

Trigger

User asks about:

• SSH session persistence / “reprendre après reconnexion”
• tmux not working properly or not auto-attaching
• “j’ai installé tmux/Mosh mais ça ne fonctionne pas”
• Connection drops killing terminal work

Diagnostic Checklist

1. Est-ce que tmux est installé ?

which tmux
tmux -V

Si absent → sudo apt install tmux

2. Est-ce qu’une session tmux existe déjà ?

tmux list-sessions

Si une session active existe (ex: “travail”), le problème est ailleurs.

3. Est-ce que ~/.tmux.conf existe ?

ls -la ~/.tmux.conf

Si absent → tmux tourne en config usine : pas de souris, historique 2000 lignes, pas de 256 couleurs. Créer le fichier (voir référence templates/tmux.conf).

4. Vérifier les réglages actifs de tmux

tmux show -g default-terminal
tmux show -g history-limit
tmux show -g mouse

5. Auto-attach au SSH ?

grep -n 'tmux attach\|TMUX' ~/.bashrc

Si absent → l’utilisateur tombe dans un bash nu. Ajouter auto-attach :

# À la fin de ~/.bashrc
[ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ] && \
  { tmux attach -t travail 2>/dev/null || tmux new -s travail; }

6. Mosh optionnel (connexions instables)

which mosh-server
mosh-server --version

Mosh résiste aux changements d’IP (veille, changement de réseau). tmux résiste aux déconnexions. Ensemble : solution complète.

Configuration complète

Création de ~/.tmux.conf

Voir le template dans templates/tmux.conf.

Paramètres clés :

• set -g mouse on — navigation à la souris
• set -g default-terminal "tmux-256color" — 256 couleurs
• set -g history-limit 10000 — historique confortable
• set -g escape-time 50 — réactivité, pas de lag
• set -g base-index 1 — indexation naturelle
• Barre de status en haut avec hostname + heure

Ajout à ~/.bashrc

Alias utiles :

alias ta='tmux attach -t travail 2>/dev/null || tmux new -s travail'
alias tl='tmux list-sessions'
alias tks='tmux kill-session -t'
alias tr='tmux source-file ~/.tmux.conf && echo "✓ rechargé"'

Pour l’auto-attach automatique, décommenter le bloc :

[ -n "$SSH_CONNECTION" ] && [ -z "$TMUX" ] && \
  { tmux attach -t travail 2>/dev/null || tmux new -s travail; }

Activation du fichier tmux.conf

tmux source-file ~/.tmux.conf

Ou dans tmux : Ctrl+B r (si le raccourci est configuré).

Pitfalls

⚠️ Sécurité : modification de .bashrc bloquée

Le patch/write_file refuse la modification de .bashrc (fichier protégé). → Utiliser cat >> ~/.bashrc << 'EOF' en terminal. L’utilisateur doit approuver la commande quand l’outil demande confirmation.

Pour décommenter l’auto-attach existant dans .bashrc (ne pas réécrire tout le fichier) :

sed -i '148,151c\# AUTO-ATTACH active — SSH → tmux session "travail"\n[ -n "$SSH_CONNECTION" ] \&\& [ -z "$TMUX" ] \&\& \\\n  { tmux attach -t travail 2>/dev/null || tmux new -s travail; }\n#' ~/.bashrc

⚠️ Attention : sed -i avec c\ remplace une plage de lignes. Si les numéros de ligne ne sont plus à jour (lignes ajoutées/supprimées entre-temps), utiliser un grep préalable pour trouver les bonnes lignes : grep -n 'SSH_CONNECTION\\|auto-attach\\|tmux attach' ~/.bashrc

⚠️ Auto-attach ne doit s’activer que sur SSH

Toujours tester $SSH_CONNECTION avant l’auto-attach, sinon tmux se lance aussi dans les terminaux locaux (gnome-terminal, etc.) et crée des tmux imbriqués.

⚠️ Ne pas imbriquer tmux dans tmux

Tester [ -z "$TMUX" ] avant de lancer tmux. $TMUX est défini quand on est déjà dans tmux.

⚠️ Mosh nécessite des ports UDP

Mosh utilise les ports 60000-61000 UDP. Si UFW/firewall est actif, ouvrir :

sudo ufw allow in on tailscale0 to any port 60000:61000 proto udp

(ou sur l’interface concernée, pas forcément tailscale0)

⚠️ tmux-256color vs xterm-256color

Si le terminal distant ne supporte pas tmux-256color, tmux peut refuser de démarrer. Replier sur screen-256color ou xterm-256color si besoin.

⚠️ La session tmux porte un nom explicite

Utiliser -t travail ou -t dev — pas de session sans nom. Plus facile à retrouver et à documenter.

⚠️ Ne pas empiler plusieurs sed -i sur la même plage

Multiples sed -i successifs sur les mêmes lignes peut dupliquer le contenu (chaque sed décale les lignes suivantes). Préférer un seul sed -i avec une expression composée, ou le c\ qui remplace toute une plage d’un coup.

Verification

Après toute modification de .bashrc ou .tmux.conf, valider :

Syntaxe bashrc

bash -n ~/.bashrc && echo "✓ syntaxe OK"

Syntaxe tmux.conf

tmux source-file ~/.tmux.conf && echo "✓ config valide"

Ou Ctrl+B r si déjà dans tmux (avec le raccourci bind r source-file configuré).

Simulation auto-attach (hors SSH réel)

SSH_CONNECTION="test" TMUX="" bash -c 'source ~/.bashrc; tmux has -t travail 2>&1 && echo "✓ auto-attach OK"' 

Ce test simule une connexion SSH, vérifie que le source du bashrc ne plante pas, et que la session tmux est bien rattachée.

Application à la session tmux en cours (sans déconnexion)

tmux source-file ~/.tmux.conf

Cette commande recharge la config dans le tmux serveur (pas besoin d’être dans un pane tmux pour l’exécuter).

Intégration Mosh (connexion complète)

Connexion recommandée :

mosh bf@<host> -- tmux attach -t travail || tmux new -s travail

Ou en deux temps :

mosh bf@<host>   # connexion résiliente
ta               # alias : attache/rejoint tmux

Rappels pour l’utilisateur

• Après déconnexion involontaire : reconnecte-toi et tape ta
• Avec auto-attach : tu es automatiquement remis dans ta session
• Ctrl+B d → détacher sans quitter la session
• Ctrl+B r → recharger la config tmux
• Ctrl+B , → renommer la fenêtre courante