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

- Link: https://dpioch.aristeecampus.org/documents-personnels-du-homelab-docx-et-html/hl-prc-013-guacamole-redirection-de-lecteur-rdp/
- Published: 2026-11-02T19:53:01+01:00
- Author: Admin

| HOMELAB
Infrastructure auto-hébergée |

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.

| Référence
HL-PRC-013 | Version0.1 | Date d’édition25/10/2026 | 
| AuteurAdministrateur système et réseaux | ClassificationInterne | StatutBrouillon |

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

| Rôle | Responsabilité | 
| Administrateur | Configure la connexion RDP dans Guacamole, définit le chemin Linux du lecteur, vérifie les permissions du démon guacd et valide les flux réseau. | 
| Détenteur des secrets | Consigne les identifiants d’accès au portail Guacamole et à la session Windows dans le gestionnaire de secrets Vaultwarden. | 
| Exploitant | Utilise le glisser-déposer pour téléverser les fichiers et extrait les documents distants via le dossier virtuel Download. |

**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

| Paramètre | Description | Valeur de référence | Contrainte | 
| GUAC_HOST_IP | Adresse IP de la passerelle Guacamole | 10.10.10.20 | Accessible en HTTP/HTTPS | 
| RDP_TARGET_IP | Adresse IP de la machine cible Windows | [À COMPLÉTER] | Port TCP 3389 ouvert | 
| DRIVE_ENABLED | Activation du lecteur virtuel | true (Coché) | Paramètre de connexion | 
| DRIVE_NAME | Nom du lecteur virtuel exposé à Windows | partage | Chaîne alphanumérique | 
| DRIVE_PATH | Répertoire tampon sur l’hôte Linux guacd | /tmp/guacamole-drive | Accessible en écriture | 
| AUTO_CREATE_PATH | Création automatique du répertoire | true (Coché) | Créé par guacd si absent | 
| UNC_PATH_REMOTE | Chemin UNC interne dans la session distante | \\tsclient\partage | Canal virtuel RDP |

**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:

| Situation | Action | 
| Dysfonctionnement ou blocage des transferts suite à la configuration | Décocher la case « Activer lecteur réseau » dans la section « Redirection Périphérique » de la connexion, enregistrer, et redémarrer la session RDP. | 
| Saturation de l’espace disque du serveur hôte guacd | Se connecter sur l’hôte Linux Guacamole et Avant cette purge destructive, vérifier qu’aucun transfert n’est en cours et conserver les fichiers encore utiles, puis purger : rm -rf /tmp/guacamole-drive/* |

Pièges connus

| Symptôme | Cause | Résolution | 
| Le raccourci clavier Ctrl+C sur le poste client suivi de Ctrl+V dans la session distante ne colle aucun fichier. | Le presse-papier HTML5 du navigateur est restreint par sécurité aux chaînes de caractères (texte/HTML) et n’expose pas de descripteurs de fichiers système. | Utiliser exclusivement le glisser-déposer (Drag & Drop) depuis le poste client sur la fenêtre du navigateur Guacamole pour déposer les fichiers dans le lecteur virtuel. | 
| La connexion au lecteur réseau n’a pas pu être créée car l’erreur suivante s’est produite : Tentative d’accès à une adresse non valide. | Tentative de monter \\10.10.10.20\tsclient\partage ou \\tsclient\partage via l’assistant Windows « Connecter un lecteur réseau » depuis le poste physique. Le chemin tsclient est un canal virtuel RDP interne, non un serveur SMB écoutant sur le port TCP 445. | Annuler l’assistant de lecteur réseau sur le poste client. Sur l’hôte physique, tous les transferts s’opèrent par l’interface web (glisser-déposer et dossier Download). Dans la session Windows, le lecteur est déjà monté sous « Ce PC » ou accessible via \\tsclient\partage. | 
| Options de lecteur introuvables (« ya pas ») dans les paramètres de la connexion. | La rubrique est traduite par « Lecteur réseau » dans la section « Redirection Périphérique », ou la connexion cible n’est pas de type RDP (les protocoles SSH et VNC n’utilisent pas ce canal mais l’intégration SFTP). | Vérifier que le protocole de la connexion est bien RDP, se rendre dans la section « Redirection Périphérique » et cocher « Activer lecteur réseau » (Enable drive). | 
| Le lecteur « partage sur Guacamole RDP » n’apparaît pas dans l’Explorateur Windows après modification. | La session RDP existante a été maintenue ouverte. Les périphériques redirigés RDPDR ne sont initialisés qu’à la connexion initiale de la session. | Fermer complètement la session RDP (Déconnexion de l’utilisateur distant) et relancer la connexion depuis le portail Guacamole. |

## 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.

| Composant | Rôle dans l’architecture | Adresse IP de référence | Ports d’écoute | 
| Passerelle Guacamole | Serveur web portail HTML5 | 10.10.10.20 | TCP 80, 443 (ou 8080) | 
| Démon guacd | Traducteur de protocoles natifs | 10.10.10.20 (local) | TCP 4822 (écoute locale) | 
| Serveur Windows cible | Hôte de session distante | [À COMPLÉTER] | TCP 3389 (service RDP) | 
| Poste client physique | Poste opérateur d’accès | Attribution DHCP | Ports éphémères source |

| Source | Destination | Port / Protocole | Usage | 
| Poste client | Passerelle Guacamole | TCP 443 (HTTPS / WSS) | Session interactive et transit de fichiers | 
| Portail Guacamole | Démon guacd | TCP 4822 (Guacamole) | Instructions d’affichage et flux de canal | 
| Démon guacd | Serveur Windows cible | TCP 3389 (RDP / RDPDR) | Affichage bureau et canal virtuel de disque | 
| Poste client | Serveur Windows cible | TCP 445 (SMB / CIFS) | NON REQUIS (Flux direct interdit) |

## 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

| Point | Impact | État | 
| Purge automatisée du stockage temporaire | Risque d’accumulation de fichiers volumineux sous /tmp/guacamole-drive. | Accepté. Script de purge tmpwatch ou tâche cron à qualifier. | 
| Analyse antivirale des fichiers en transit | Absence d’inspection des fichiers téléversés au niveau de la passerelle Guacamole. | Accepté pour le lab. Protection assurée par l’antivirus de la machine cible Windows. | 
| Isolation mono-dossier par défaut | Le chemin /tmp/guacamole-drive est partagé entre sessions si la variable ${GUAC_USERNAME} n’est pas renseignée. | Conforme à l’usage homelab individuel. Variable documentée en section 4. |

## 7 Vérifications finales

| Contrôle | Critère d’acceptation | Statut | 
| Configuration de la connexion RDP | Option « Activer lecteur réseau » cochée avec nom « partage » et chemin « /tmp/guacamole-drive » | ☐ | 
| Création du répertoire sur l’hôte guacd | Répertoire /tmp/guacamole-drive existant avec permissions d’écriture pour le processus guacd | ☐ | 
| Montage du lecteur virtuel distant | Explorateur Windows > Ce PC affiche « partage sur Guacamole RDP » sous « Dossiers et lecteurs redirigés » | ☐ | 
| Test de téléversement (Upload) | Glisser-déposer d’un fichier sur la fenêtre web : le fichier est lisible dans « partage sur Guacamole RDP » | ☐ | 
| Test de rapatriement (Download) | Dépôt d’un fichier distant dans le sous-dossier « Download » : téléchargement automatique déclenché par le navigateur | ☐ | 
| Transfert d’une arborescence complète | Archive .zip téléversée par glisser-déposer et décompressée avec succès sur la machine cible | ☐ |

## 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

| Version | Date | Auteur | Modifications | 
| 0.1 | 25/10/2026 | Administrateur système et réseaux | Création du document à partir de l’intervention réelle. |