HL-PRC-013 — Guacamole — redirection de lecteur RDP

PROCÉDURE TECHNIQUE

Redirection de lecteur virtuel RDP sous Apache Guacamole

Mise en œuvre du canal de lecteur virtuel RDP et du transfert bidirectionnel de fichiers par interface web pour les sessions distantes Windows.

Sommaire

Redirection de lecteur virtuel RDP sous Apache Guacamole — HL-PRC-013

1 Objet

Cette procédure formalise la configuration du canal virtuel de redirection de disque RDP (Device Redirection) sur la passerelle d’accès Apache Guacamole afin de permettre le transfert bidirectionnel de fichiers entre le poste client et une session distante Windows. L’opération consiste à activer le lecteur virtuel dans la configuration de la connexion RDP, à définir un répertoire tampon sur l’hôte exécutant le démon guacd, puis à valider l’apparition du lecteur réseau émulé dans l’Explorateur de fichiers de la machine distante. À l’issue de la procédure, l’opérateur dépose des fichiers par simple glisser-déposer sur la fenêtre du navigateur web et extrait des documents vers son poste physique via le sous-répertoire virtuel Download.

La difficulté principale traitée réside dans la séparation d’architecture entre le client web HTML5 et le protocole RDP sous-jacent. Le presse-papier du navigateur ne permet pas le transit direct d’objets du système de fichiers par raccourci clavier (Ctrl+C / Ctrl+V), et le canal virtuel tsclient n’est pas un partage de fichiers SMB accessible depuis le réseau local du poste client. La procédure documente le fonctionnement réel du lecteur virtuel, élimine les tentatives erronées de mappage réseau depuis l’hôte physique, et traite le cas spécifique du transfert des répertoires nécessitant une compression préalable.

2 Périmètre et prérequis

Périmètre

Couvert : configuration des paramètres de redirection de périphériques RDP dans l’interface d’administration Guacamole, création et attribution des permissions sur le répertoire tampon Linux sous /tmp/guacamole-drive, validation du montage automatique du lecteur sous Windows (Ce PC > Dossiers et lecteurs redirigés), procédures opératoires de téléversement (glisser-déposer) et de téléchargement (dossier Download).

Hors périmètre : installation initiale de la pile Apache Guacamole et du démon guacd, configuration du service RDP ou de l’authentification Active Directory sur le serveur Windows distant, mise en place d’un partage réseau de fichiers SMB/CIFS d’entreprise ou d’un stockage cloud tiers (Nextcloud, OneDrive).

Note Version validée et environnement réel. Intervention validée sur Apache Guacamole 1.5.x avec démon guacd sous Debian Linux, passerelle joignable sur l’adresse 10.10.10.20, et cible distante exécutant Microsoft Windows Server / Windows 11 en session RDP standard (port TCP 3389).

Prérequis

• Accès d’administration Guacamole : disposer d’un compte avec privilèges de gestion des connexions (Paramètres > Connexions).

• Session RDP fonctionnelle : connexion RDP vers la machine distante Windows préalablement créée et validée.

• Droits d’écriture sur l’hôte guacd : autorisation de créer ou d’écrire dans le chemin système /tmp/guacamole-drive par l’utilisateur exécutant le démon guacd.

• Navigateur compatible HTML5 : navigateur moderne (Google Chrome, Mozilla Firefox, Microsoft Edge) supportant l’API Drag and Drop et les téléchargements de fichiers.

3 Rôles et responsabilités

Note Homelab individuel. Dans le cadre d’un homelab individuel, l’ensemble de ces rôles est assumé par la même personne physique. La distinction fonctionnelle est conservée afin d’assurer la traçabilité des opérations de maintenance.

4 Procédure de configuration

Paramètres de la procédure

Attention Substitution des paramètres. Les blocs de configuration et les explications ci-dessous reprennent directement les valeurs réelles appliquées sur le lab (adresse passerelle 10.10.10.20, nom de lecteur partage et chemin /tmp/guacamole-drive). Ne pas substituer ces paramètres sans adapter les autorisations locales sur le serveur guacd.

Étapes d’exécution

1. Accéder aux paramètres de la connexion RDP dans l’interface Guacamole

Pour modifier les paramètres de redirection de périphériques, la connexion ne doit pas être en cours d’édition dans une session ouverte. Les réglages s’effectuent dans le panneau d’administration centralisé de Guacamole.

• Navigation : Se connecter à l’interface web Guacamole avec le compte administrateur, cliquer sur le nom d’utilisateur en haut à droite > Paramètres (Settings), puis ouvrir l’onglet Connexions (Connections).

• Sélection : Cliquer sur la connexion RDP ciblée pour afficher sa page de configuration.

Vérification : La page d’édition de la connexion s’affiche, présentant l’ensemble des rubriques de configuration (Paramètres réseau, Authentification, Redirection Périphérique).

2. Activer et paramétrer la redirection du lecteur virtuel

Le protocole RDP dispose d’un canal virtuel de redirection de disque (RDPDR) géré côté passerelle par guacd. Guacamole doit allouer un répertoire local pour matérialiser ce stockage virtuel et l’exposer au système d’exploitation distant.

• Rubrique : Faire défiler la page jusqu’à la section Redirection Périphérique (Device Redirection).

• Activer lecteur réseau : Cocher la case (valeur true).

• Nom du lecteur : Saisir partage (nom visible dans l’Explorateur Windows).

• Options de transfert : Laisser décochées les cases Désactiver le téléchargement de fichier et Désactiver l’envoi de fichier.

• Chemin du lecteur : Saisir /tmp/guacamole-drive (répertoire de transit sur le serveur Linux hébergeant guacd).

• Créer automatiquement le chemin du lecteur : Cocher la case afin que guacd initialise le dossier s’il n’existe pas.

• Enregistrement : Cliquer sur le bouton Enregistrer tout en bas de la page.

Vérification : L’interface enregistre la configuration sans erreur et bascule sur la liste des connexions.

3. Fermer et rouvrir la session RDP pour initialiser le lecteur virtuel

La négociation des canaux virtuels RDP (notamment le canal de système de fichiers RDPDR) n’intervient qu’au moment du handshake initial de la session. Une session existante laissée active ou simplement déconnectée ne prend pas en compte les nouveaux périphériques redirigés.

• Fermeture complète : Si une session était ouverte sur la machine Windows, la fermer impérativement (Déconnexion / Sign out du compte Windows, et non simple fermeture de l’onglet du navigateur).

• Connexion : Depuis l’accueil Guacamole, cliquer sur la connexion Windows pour démarrer une nouvelle session RDP.

• Consultation : Dans la session Windows, ouvrir l’Explorateur de fichiers et sélectionner Ce PC.

Vérification : Sous la section Dossiers et des lecteurs redirigés (1), l’icône et l’intitulé partage sur Guacamole RDP apparaissent. Le chemin UNC interne correspond à \\tsclient\partage.

4. Téléverser un fichier du poste client vers la machine distante (Glisser-Déposer)

Le presse-papier web ne transmettant pas les objets fichiers par copier-coller classique (Ctrl+C / Ctrl+V), le téléversement s’opère par l’interception de l’événement de glisser-déposer HTML5 par Guacamole, qui écrit le flux dans le lecteur virtuel.

• Action opérateur : Sur le poste physique local, sélectionner un fichier et le glisser-déposer directement sur la fenêtre du navigateur web affichant la session Guacamole.

• Résultat attendu : Une notification de téléversement s’affiche brièvement dans l’interface web. Le fichier apparaît immédiatement dans le lecteur virtuel partage sur Guacamole RDP.

Déplacement local : Dans la session Windows distante, l’opérateur peut copier ou déplacer le fichier depuis ce lecteur vers n’importe quel dossier local (Bureau, Documents, disque C:).

5. Rapatrier un fichier de la machine distante vers le poste client (Téléchargement)

La passerelle Guacamole surveille en continu le sous-dossier spécial Download présent à la racine du lecteur émulé ; tout fichier y étant déposé déclenche une émission de flux HTTP vers le navigateur client.

• Accès : Dans l’Explorateur de la session Windows, ouvrir le lecteur partage sur Guacamole RDP.

• Dépôt : Ouvrir le sous-dossier virtuel nommé Download, puis y copier ou glisser le fichier distant souhaité.

Vérification : Le navigateur web du poste physique déclenche instantanément le téléchargement du fichier, qui est enregistré dans le répertoire habituel de téléchargements locaux de l’opérateur.

6. Appliquer la méthode de transfert d’arborescences de dossiers

L’API de glisser-déposer web de Guacamole ne prend pas en charge la création récursive d’arborescences de dossiers brutes lors d’un dépôt direct.

• Compression source : Sur le poste physique local, compresser le dossier complet sous la forme d’une archive .zip.

• Transfert : Glisser-déposer l’archive .zip sur l’interface Guacamole.

• Extraction cible : Dans la session Windows distante, ouvrir l’archive reçue dans partage sur Guacamole RDP et l’extraire vers l’emplacement de travail souhaité.

Vérification : L’archive est transférée sans altération et l’arborescence décompressée préserve l’ensemble de ses sous-dossiers et fichiers.

Retour arrière

En cas de dysfonctionnement des transferts, de dégradation des performances réseau ou de saturation du stockage temporaire, appliquer les actions correctives ci-dessous :

Pièges connus

5 Intégration réseau

Le dispositif s’appuie sur l’architecture passerelle Apache Guacamole. Les flux de données de fichiers transitent encapsulés dans le flux de contrôle HTTP/WebSocket entre le navigateur et la passerelle, puis dans le canal virtuel RDPDR (port TCP 3389) entre le démon guacd et la cible Windows. Aucun port de partage de fichiers SMB standard (TCP 445) n’est exposé vers le poste client.

6 Durcissement et sécurité

• Isolation stricte des utilisateurs : Sur une infrastructure accueillant plusieurs opérateurs, utiliser la variable dynamique ${GUAC_USERNAME} dans le chemin du lecteur (/tmp/guacamole-drive/${GUAC_USERNAME}) afin que guacd sépare strictement les répertoires et empêche la consultation croisée des fichiers déposés entre utilisateurs.

• Contrôle des flux d’exfiltration : Dans les environnements soumis à des contraintes d’étanchéité de données, activer l’option Désactiver le téléchargement de fichier pour empêcher l’extraction de données confidentielles de la machine distante vers le poste client.

• Gestion stricte des permissions locales : Restreindre les droits d’accès sur l’hôte Linux pour que seul le compte système exécutant le démon guacd (utilisateur guacd ou daemon) dispose des privilèges de lecture/écriture sur le répertoire de stockage temporaire /tmp/guacamole-drive.

• Purge programmée du tampon : Mettre en place une tâche cron ou un temporisateur systemd pour vider automatiquement les fichiers résiduels sous /tmp/guacamole-drive afin d’éviter la saturation de la partition racine.

Dettes techniques

7 Vérifications finales

8 Références et historique des révisions

Documentation éditeur

• Apache Software Foundation : Apache Guacamole Manual 1.5.0 — Chapter 5: Configuring Guacamole (RDP drive redirection, static virtual channels and file transfer parameters).

• Microsoft Corporation : Spécification technique [MS-RDPEFS] — Remote Desktop Protocol: File System Virtual Channel Extension.

• Microsoft Corporation : Documentation Windows Server — Remote Desktop Services Client Drive and Device Redirection.

Documents associés

• HL-PRC-010 : Configuration d’une connexion SSH par clé dans Apache Guacamole (portail d’accès d’administration).

• HL-PRC-003 : Mise en service d’une grappe de virtualisation Proxmox VE (infrastructure d’accueil).

Historique des révisions