> ## Documentation Index
> Fetch the complete documentation index at: https://private-7c7dfe99-fix-nav-issues.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> Documentación del terminal web, una sesión de `clickhouse-client` en el navegador a través de WebSocket

# Terminal web

El terminal web es una interfaz experimental en el navegador que proporciona una sesión interactiva de `clickhouse-client` a través de WebSocket. Está disponible en cualquier puerto HTTP de ClickHouse en la ruta `/webterminal`.

<Note>
  El terminal web es una función experimental y está desactivado de forma predeterminada; consulta [Habilitar la función](#enabling-the-feature) a continuación.
</Note>

<div id="enabling-the-feature">
  ## Habilitar la funcionalidad
</div>

El endpoint `/webterminal` está controlado por la configuración del servidor `allow_experimental_webterminal`. Cuando esta configuración es `false` (el valor predeterminado), las solicitudes a `/webterminal` devuelven el estado HTTP `403 Forbidden`.

Para habilitarlo, añade lo siguiente a la configuración del servidor:

```xml theme={null}
<clickhouse>
    <allow_experimental_webterminal>true</allow_experimental_webterminal>
</clickhouse>
```

Después de habilitarlo, ve a `/webterminal` en cualquier puerto HTTP de ClickHouse (por ejemplo, `http://localhost:8123/webterminal`) para abrir el terminal.

<div id="authentication">
  ## Autenticación
</div>

El terminal web autentica al usuario con las mismas comprobaciones de `Session` y de control de acceso que el protocolo HTTP, pero las credenciales se intercambian por el propio canal a través de la conexión WebSocket ya establecida, en lugar de hacerlo mediante la solicitud HTTP de actualización. Una vez completado el handshake de WebSocket, el navegador envía el primer mensaje en formato JSON:

```json theme={null}
{"type": "auth", "user": "<user>", "password": "<password>"}
```

Esto evita poner credenciales en los parámetros de consulta de la URL o en los encabezados `Authorization` enviados con la solicitud de actualización, donde podrían acabar en el historial del navegador, en los registros de acceso del servidor y en los registros del proxy inverso. Los parámetros de URL, HTTP Basic y los encabezados `X-ClickHouse-User`/`X-ClickHouse-Key` de la solicitud de actualización deliberadamente **no** se tienen en cuenta en `/webterminal`.

Las credenciales no válidas hacen que el servidor cierre el WebSocket con el código `1008`; la interfaz de usuario del navegador vuelve a solicitar las credenciales.

<div id="session">
  ## Cómo es la sesión
</div>

Una vez autenticado, el servidor ejecuta `clickhouse-client` asociado a un pseudoterminal y canaliza su entrada y salida a través de WebSocket. La sesión ofrece toda la experiencia de `clickhouse-client`, lo que incluye:

* Resaltado de sintaxis.
* Autocompletado.
* Consultas de varias líneas.
* Historial de comandos (almacenado en el servidor mientras dura la sesión).

La terminal usa [xterm.js](https://xtermjs.org/) para renderizar. Todos los recursos se sirven desde el propio binario de ClickHouse; no se carga ninguna CDN de terceros.

<div id="play-integration">
  ## Integración con `/play`
</div>

La interfaz web SQL [`/play`](/es/concepts/features/interfaces/http) incorpora el terminal web como un panel acoplable. Actívalo con el icono del terminal en la barra lateral o pulsa la tecla `~` cuando el editor de consultas esté vacío. La página `/play` detecta la disponibilidad de `/webterminal` al cargarse y oculta los controles del terminal cuando el endpoint no está disponible (por ejemplo, cuando la configuración experimental no está activada).

<div id="security">
  ## Consideraciones de seguridad
</div>

El terminal web expone una sesión interactiva similar a un shell a cualquier persona que pueda autenticarse en el endpoint HTTP de ClickHouse, por lo que aquí se aplican las mismas advertencias que para el protocolo HTTP:

* Sirve siempre `/webterminal` mediante HTTPS en entornos no confiables para proteger las credenciales y el tráfico de la sesión.
* Restringe el acceso a nivel de red (`firewall`, proxy inverso o la configuración `listen_host`) del mismo modo que restringes el acceso al protocolo HTTP.
* El endpoint valida el encabezado `Origin` con `Host` para mitigar el secuestro de WebSocket entre orígenes; configura los proxies inversos en consecuencia si terminas TLS de forma externa.
* Detrás de un proxy inverso que termina TLS, la conexión ascendente a ClickHouse usa `http` sin cifrar aunque el navegador use `https`, por lo que la comprobación estricta del mismo origen rechazaría conexiones legítimas. Para estas implementaciones, establece `webterminal_allowed_origins` como una lista de orígenes completos separados por comas a los que se permite abrir sesiones de WebSocket; cuando esta configuración no está vacía, reemplaza la comprobación predeterminada del mismo origen. Ejemplo: `<webterminal_allowed_origins>https://example.com,https://app.example.com:8443</webterminal_allowed_origins>`.

El controlador también exige la conformidad con el protocolo WebSocket según la RFC 6455: las tramas de cliente sin enmascarar, los códigos de operación reservados, las tramas de control demasiado grandes o fragmentadas y los bits RSV reservados se rechazan con códigos de cierre por error de protocolo.

<div id="platform">
  ## Disponibilidad de la plataforma
</div>

El manejador se compila en todas las plataformas compatibles con ClickHouse. La capa de seudoterminal utilizada por el ejecutor integrado de `clickhouse-client` está implementada sobre primitivas POSIX portátiles (`posix_openpt`/`grantpt`/`unlockpt`), con una implementación específica para Linux que utiliza `ptsname_r`, que es seguro para hilos. Los enlaces a `/webterminal` en la página de inicio de ClickHouse y en `/play` se ocultan automáticamente cuando el endpoint no está disponible (por ejemplo, cuando `allow_experimental_webterminal` no está habilitado).