📖 Guide d’utilisation de xsshend

Guide complet pour maßtriser xsshend - Téléversement SSH parallÚle avec interface TUI moderne

🎯 Vue d’ensemble

xsshend est un outil Rust moderne pour le téléversement parallÚle de fichiers vers multiples serveurs SSH. Il offre une interface TUI hiérarchique intuitive avec suivi en temps réel des transferts.

🚀 Installation et premier lancement

Installation via Cargo

cargo install xsshend

Premier lancement

# Lancement initial - crée automatiquement la configuration
xsshend list

⚙ Configuration automatique

Au premier lancement, xsshend :

  1. DĂ©tecte l’absence du fichier ~/.ssh/hosts.json
  2. Crée automatiquement le répertoire ~/.ssh si nécessaire
  3. Copie un fichier d’exemple vers ~/.ssh/hosts.json
  4. Vérifie la présence de clés SSH
  5. Propose la gĂ©nĂ©ration d’une clĂ© Ed25519 si aucune n’est trouvĂ©e
  6. Guide l’utilisateur dans la configuration

Structure créée automatiquement

~/.ssh/
├── hosts.json          # Configuration serveurs (crĂ©Ă© automatiquement)
├── id_ed25519          # ClĂ© privĂ©e SSH (gĂ©nĂ©rĂ©e si acceptĂ©e)
├── id_ed25519.pub      # ClĂ© publique SSH
└── config              # Configuration SSH (optionnel)

🎼 Premiers transferts

Interface de listage avec Ă©tiquettes CLI

La commande xsshend list (ou xsshend -l) affiche maintenant un aperçu hiĂ©rarchique enrichi avec des Ă©tiquettes CLI pour faciliter l’utilisation en ligne de commande :

xsshend list

Exemple de sortie :

🔍 Liste des cibles SSH disponibles:

📁 Production (--env Production)
  📂 Region-A (--region Region-A)
    📂 Public (--type Public)
      đŸ–„ïž  WEB_SERVER_01 → web01@prod-web-01.example.com (PROD)
      đŸ–„ïž  API_SERVER_01 → api01@prod-api-01.example.com (PROD)
    📂 Private (--type Private)
      đŸ–„ïž  DATABASE_01 → db01@prod-db-01.example.com (PROD)

📁 Staging (--env Staging)
  📂 Region-A (--region Region-A)
    📂 Public (--type Public)
      đŸ–„ïž  STAGE_WEB_01 → web01@stage-web-01.example.com (STAGE)

📊 Total: 4 cibles disponibles

💡 Exemples d'utilisation:
   xsshend upload --env Production file.txt
   xsshend upload --env Staging --region Region-A file.txt
   xsshend upload --region Region-A --type Public file.txt

Utilisation des Ă©tiquettes CLI

Les Ă©tiquettes facilitent la construction des commandes de filtrage :

Filtrage par environnement

# DĂ©ployer sur tout l'environnement Production
xsshend upload --env Production deploy.sh

# DĂ©ployer sur l'environnement Staging
xsshend upload --env Staging config.json

Filtrage combiné environnement + région

# DĂ©ployer sur Production dans la Region-A uniquement
xsshend upload --env Production --region Region-A app.jar

# Déployer sur Staging dans une région spécifique
xsshend upload --env Staging --region Region-B logs.tar.gz

Filtrage par environnement + type

# DĂ©ployer sur les serveurs publics de Production
xsshend upload --env Production --type Public web-assets.zip

# Déployer sur les serveurs privés de Staging
xsshend upload --env Staging --type Private database-backup.sql

Filtrage traditionnel (région ou type seulement)

# Déployer sur tous les serveurs d'une région
xsshend upload --region Region-A monitoring.sh

# DĂ©ployer sur tous les serveurs d'un type
xsshend upload --type Public static-files.tar.gz

Vérification de connectivité

La nouvelle option --online-only permet de vĂ©rifier la connectivitĂ© des serveurs avant de lancer l’interface TUI :

# Lance le TUI en n'affichant que les serveurs en ligne
xsshend --online-only

Cette option :

  • Teste la connectivitĂ© SSH vers chaque serveur avec un timeout (5 secondes par dĂ©faut)
  • Filtre automatiquement les serveurs hors ligne
  • Affiche seulement les serveurs accessibles dans l’interface TUI
  • AmĂ©liore les performances en Ă©vitant les timeouts pendant les transferts

Interface utilisateur hiérarchique

Principe

L’interface organise vos serveurs en arbre hiĂ©rarchique :

  • Environnements (Production, Staging, Development) - Filtrable avec --env
  • RĂ©gions (Region-A, Region-B, Local, etc.) - Filtrable avec --region
  • Types de serveurs (Public, Private, Services, etc.) - Filtrable avec --type
  • Serveurs individuels avec leurs alias SSH

Écran de sĂ©lection des fichiers

  • ↑↓ : Naviguer dans la liste des fichiers/dossiers
  • Espace : SĂ©lectionner/dĂ©sĂ©lectionner un fichier
  • EntrĂ©e : Entrer dans un dossier ou remonter au parent
  • h : Aller au rĂ©pertoire home
  • a : SĂ©lectionner tous les fichiers visibles
  • c : Vider la sĂ©lection
  • Tab : Passer Ă  l’écran suivant (sĂ©lection des serveurs)
  • q : Quitter l’application

Écran de sĂ©lection des serveurs

  • ↑↓ : Naviguer dans l’arbre hiĂ©rarchique
  • → ou EntrĂ©e : DĂ©plier un nƓud / SĂ©lectionner un serveur
  • ← : RĂ©duire un nƓud ou remonter au parent
  • Espace : SĂ©lectionner/dĂ©sĂ©lectionner un serveur
  • / : Activer le mode recherche
  • a : SĂ©lectionner tous les serveurs visibles
  • c : Vider la sĂ©lection de serveurs
  • Tab : Passer Ă  l’écran suivant (destination)

Mode recherche

  • CaractĂšres : Taper pour filtrer en temps rĂ©el
  • Backspace : Effacer un caractĂšre
  • EntrĂ©e : Valider et sortir du mode recherche
  • Échap : Annuler la recherche

Écran de destination

  • CaractĂšres : Taper le chemin de destination
  • EntrĂ©e : Valider et passer au tĂ©lĂ©versement
  • Échap : Revenir Ă  l’écran prĂ©cĂ©dent

Écran de progression

  • q : Quitter aprĂšs la fin des transferts
  • p : Mettre en pause/reprendre (si supportĂ©)

Modes d’utilisation

1. Mode interface complÚte (recommandé)

Lancez l’application sans arguments pour accĂ©der Ă  l’interface complĂšte :

xsshend

Cette interface vous guide Ă  travers toutes les Ă©tapes :

  1. SĂ©lection des fichiers
  2. Sélection des serveurs (interface hiérarchique)
  3. Choix de la destination
  4. Téléversement avec barre de progression

2. Mode interactif avec fichiers pré-sélectionnés

xsshend --interactive file1.txt file2.txt

ou

xsshend upload file1.txt file2.txt --interactive

Les fichiers sont prĂ©-sĂ©lectionnĂ©s, vous n’avez qu’à choisir les serveurs et la destination.

3. Mode ligne de commande avec filtres

# Téléverser vers tous les serveurs de production
xsshend upload file.txt --env Production --dest /opt/app/

# Téléverser vers une région spécifique
xsshend upload *.log --env Staging --region Region-A --dest /var/log/

# Téléverser vers un type de serveurs
xsshend upload config.json --env Production --type Public --dest /etc/app/

4. Mode simulation (dry-run)

xsshend upload file.txt --env Production --dry-run

Simule le transfert sans effectuer de connexions réelles.

Configuration des serveurs

Votre fichier de configuration se trouve dans ~/.ssh/hosts.json. Voici un exemple de structure :

{
  "Production": {
    "Region-A": {
      "Public": {
        "WEB_SERVER_01": {
          "alias": "web01@prod-web-01.example.com",
          "env": "PROD"
        },
        "API_SERVER_01": {
          "alias": "api01@prod-api-01.example.com", 
          "env": "PROD"
        }
      },
      "Private": {
        "DATABASE_01": {
          "alias": "db01@prod-db-01.example.com",
          "env": "PROD"
        }
      }
    }
  },
  "Staging": {
    "Region-A": {
      "Public": {
        "STAGE_WEB_01": {
          "alias": "web01@stage-web-01.example.com",
          "env": "STAGE"
        }
      }
    }
  }
}

Liste des serveurs disponibles

# Lister tous les serveurs
xsshend list

# Filtrer par environnement
xsshend list --env Production

Conseils d’utilisation

Efficacité

  • Utilisez la recherche (/) pour filtrer rapidement les serveurs dans les grandes infrastructures
  • Utilisez a pour sĂ©lectionner tous les serveurs d’un environnement aprĂšs filtrage
  • Organisez vos serveurs par environnement → rĂ©gion → type pour une navigation optimale

Sécurité

  • Le fichier hosts.json peut contenir des informations sensibles, gardez-le sĂ©curisĂ©
  • Testez toujours sur l’environnement de staging avant la production
  • Utilisez le mode --dry-run pour vĂ©rifier vos sĂ©lections

Productivité

  • CrĂ©ez des alias dans votre shell pour les commandes frĂ©quentes
  • PrĂ©-sĂ©lectionnez les fichiers depuis la ligne de commande quand vous les connaissez
  • Utilisez l’interface hiĂ©rarchique pour explorer et dĂ©couvrir votre infrastructure

Gestion robuste des erreurs et timeouts

Serveurs déconnectés

xsshend gÚre gracieusement les serveurs inaccessibles ou déconnectés :

# Vérification préalable de connectivité (recommandé pour les grandes infrastructures)
xsshend --online-only

# Cette option :
# - Teste la connectivité SSH vers chaque serveur (timeout: 5s)
# - Filtre automatiquement les serveurs inaccessibles 
# - Affiche seulement les serveurs en ligne dans l'interface TUI
# - Évite les blocages pendant les transferts

Timeouts et retry automatique

Les connexions SSH utilisent des timeouts configurés pour éviter les blocages :

  • Timeout de connexion TCP : 5 secondes par dĂ©faut
  • Timeout du handshake SSH : 5 secondes par dĂ©faut
  • Nombre de tentatives : 2 tentatives maximum par serveur
  • DĂ©lai entre tentatives : 1 seconde

Comportement en cas d’erreur

Quand un serveur devient inaccessible pendant les transferts :

  1. Erreur loggĂ©e : L’erreur est enregistrĂ©e avec dĂ©tails
  2. Continuation : Les transferts vers les autres serveurs continuent
  3. Résumé final : Affichage des serveurs réussis vs échoués
  4. Code de sortie : SuccÚs si au moins un serveur a réussi

Exemple de sortie d’erreur gracieuse :

❌ Upload Ă©chouĂ© vers SERVER_DOWN : Timeout de connexion TCP
✅ Upload rĂ©ussi vers SERVER_01 : 1,234,567 octets
✅ Upload rĂ©ussi vers SERVER_02 : 1,234,567 octets

📊 Upload parallĂšle terminĂ© : 2/3 serveurs rĂ©ussis
⚠ Serveurs Ă©chouĂ©s : SERVER_DOWN

Debug et diagnostic

Pour diagnostiquer les problĂšmes de connexion :

# Mode debug complet
RUST_LOG=debug xsshend upload --env Production file.txt

# Test manuel de connectivité SSH
ssh -o ConnectTimeout=5 -o BatchMode=yes user@server.example.com exit

# VĂ©rifier la configuration SSH locale
ssh -v user@server.example.com