Terminal web

Documentation sur le terminal web, une session clickhouse-client dans le navigateur via WebSocket

Le terminal web est une interface dans le navigateur qui fournit une session interactive clickhouse-client via WebSocket. Il est accessible depuis n’importe quel port HTTP de ClickHouse à l’emplacement /webterminal.

Accédez à /webterminal sur n’importe quel port HTTP de ClickHouse (par exemple, http://localhost:8123/webterminal) pour ouvrir le terminal.

​

Activation et désactivation de la fonctionnalité

Le point de terminaison /webterminal est activé par défaut et contrôlé par le paramètre du serveur enable_webterminal. Pour le désactiver, définissez ce paramètre sur false ; les requêtes vers /webterminal renverront alors le code d’état HTTP 403 Forbidden.

<clickhouse>
    <enable_webterminal>false</enable_webterminal>
</clickhouse>

enable_webterminal remplace l’ancien paramètre allow_experimental_webterminal. L’ancien nom reste pris en charge par souci de rétrocompatibilité lorsque enable_webterminal n’est pas défini.

​

Authentification

Le terminal web authentifie l’utilisateur en appliquant les mêmes vérifications de Session et de contrôle d’accès que le protocole HTTP, mais les informations d’identification sont échangées directement sur la connexion WebSocket établie plutôt que via la requête de mise à niveau HTTP. Une fois la négociation initiale WebSocket terminée, le navigateur envoie le premier message au format JSON :

{"type": "auth", "user": "<user>", "password": "<password>"}

Le champ user est facultatif : lorsqu’il est omis ou vide, le nom d’utilisateur est défini par le paramètre du serveur default_session_user (ou son remplacement par point de terminaison dans une configuration de protocoles composables), à savoir default sauf configuration contraire. Si default_session_user est défini sur une chaîne vide, les connexions sans nom d’utilisateur sont interdites : un message auth dont le champ user est omis ou vide échoue à l’authentification, le serveur ferme le WebSocket avec le code 1008 et, lorsque la section session_log est activée dans la configuration du serveur, le refus est enregistré dans system.session_log en tant qu’événement LoginFailure avec un user vide.

Cela évite de placer des informations d’identification dans les paramètres d’URL ou les en-têtes Authorization associés à la requête d’upgrade, où ils pourraient se retrouver dans l’historique du navigateur, les journaux d’accès du serveur et les logs du proxy inverse. Les paramètres d’URL, l’authentification HTTP Basic et les en-têtes X-ClickHouse-User/X-ClickHouse-Key de la requête d’upgrade ne sont délibérément pas pris en compte par /webterminal.

Des informations d’identification invalides entraînent la fermeture du WebSocket par le serveur avec le code 1008 ; l’UI du navigateur redemande les informations d’identification.

​

À quoi ressemble la session

Une fois authentifié, le serveur exécute clickhouse-client, rattaché à un pseudoterminal, et transmet ses entrées et sorties via WebSocket. La session prend en charge l’expérience complète de clickhouse-client, y compris :

• Coloration syntaxique.
• Autocomplétion.
• Requêtes sur plusieurs lignes.
• Historique des commandes (stocké côté serveur pendant toute la durée de la session).

Le terminal utilise xterm.js pour l’affichage. Toutes les ressources sont servies directement par le binaire ClickHouse lui-même — aucun CDN tiers n’est chargé.

​

Intégration avec /play

L’interface Web SQL /play intègre le terminal web dans un panneau ancrable. Affichez-le ou masquez-le à l’aide de l’icône du terminal dans la barre latérale, ou appuyez sur la touche ~ lorsque l’éditeur de requêtes est vide. La page /play détecte la disponibilité de /webterminal au chargement et masque les commandes du terminal lorsque le point de terminaison n’est pas disponible (par exemple, lorsque enable_webterminal est défini sur false).

​

Intégration au site web de documentation

Ce site web de documentation intègre le même terminal dans un étroit panneau développeur en bas de page, connecté au ClickHouse playground avec l’utilisateur play en lecture seule, afin de pouvoir essayer les exemples de n’importe quelle page sans la quitter. Le panneau fixe réserve un espace équivalent en fin de page afin de ne pas masquer les contrôles du pied de page. Lorsque le terminal est ouvert, la page de documentation est verrouillée et sa barre de défilement est masquée. Le défilement dans le terminal reste limité à son historique et ne déplace pas la page de documentation située derrière. Cliquez sur la barre « ClickHouse terminal » ou appuyez sur la touche ~ pour ouvrir le panneau avec marges internes au-dessus de la barre. Cliquez de nouveau sur la barre, utilisez son chevron, appuyez sur ~ ou Escape, ou faites glisser le bord supérieur du panneau vers le bas pour le replier ; ce bord supérieur permet également de le redimensionner. La fin de la session — exit ou Ctrl+D — replie également le panneau.

La fermeture du panneau conserve la session et son historique : la réouverture du terminal vous ramène à la même invite. La session est conservée dans la page ; elle persiste donc lors de la navigation entre les pages de documentation, mais pas lors du rechargement de l’onglet du navigateur — après un rechargement, le panneau revient avec une nouvelle session.

Le panneau du terminal fait partie de la mise en page pour ordinateur du site web et n’est pas disponible dans les fenêtres d’affichage étroites.

​

Considérations de sécurité

Le terminal web expose une session interactive de type shell à quiconque peut s’authentifier sur le point de terminaison HTTP de ClickHouse. Les mêmes précautions que pour le protocole HTTP s’appliquent donc ici :

• Servez toujours /webterminal via HTTPS dans les environnements non fiables afin de protéger les informations d’identification et le trafic de session.
• Restreignez l’accès au niveau du réseau (pare-feu, proxy inverse ou configuration listen_host) de la même façon que vous restreignez l’accès au protocole HTTP.
• Le point de terminaison valide l’en-tête Origin par rapport à Host afin d’atténuer les détournements WebSocket inter-origines ; configurez les proxys inverses en conséquence si vous terminez TLS de façon externe.
• Derrière un proxy inverse qui termine TLS, la connexion en amont vers ClickHouse se fait en http simple même si le navigateur utilise https, de sorte que la vérification stricte de même origine rejetterait des connexions légitimes. Pour ces déploiements, définissez webterminal_allowed_origins sur une liste d’origines complètes autorisées à ouvrir des sessions WebSocket, séparées par des virgules ; lorsque ce paramètre n’est pas vide, il remplace la vérification de même origine par défaut. Exemple : <webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>.

Le gestionnaire applique également la conformité au protocole WebSocket conformément à la RFC 6455 : les trames client non masquées, les opcodes réservés, les trames de contrôle surdimensionnées ou fragmentées, ainsi que les bits RSV réservés sont rejetés avec des codes de fermeture pour erreur de protocole.

​

Disponibilité de la plateforme

Ce composant est compilé sur toutes les plateformes prises en charge par ClickHouse. La couche de pseudoterminal utilisée par le moteur d’exécution clickhouse-client intégré repose sur des primitives POSIX portables (posix_openpt/grantpt/unlockpt), avec un chemin de code spécifique à Linux qui utilise ptsname_r, thread-safe. Les liens vers /webterminal sur la page d’accueil de ClickHouse et dans /play sont automatiquement masqués lorsque le point de terminaison n’est pas disponible (par exemple, lorsque enable_webterminal est défini sur false).