El circuito, en vivo
Pulsa un nodo para ver qué hace, qué ve y cómo comprobarlo. El paquete morado va cifrado con TLS de punta a punta; solo el último salto, dentro de la máquina del alumno, es HTTP plano. El paquete verde es la fase de identidad: login del alumno en Keycloak y certificado SSH firmado por Vault (una vez cada 8 horas).
Pulsa un nodo
- Dónde está
- Qué ve
- Qué hace
- Fichero de configuración
- Comprobarlo
Paso a paso
El mismo recorrido en una tabla, con nombres, direcciones y el comando que lo demuestra.
| # | Componente | Dónde / IP / puerto | Qué hace | Comprobar con |
|---|
Guía del alumno
Lo que necesitas tener y lo que tienes que hacer. Tu usuario de ejemplo aquí es jviejo; sustitúyelo por el que te asigne el profesor.
Lo que necesitas tener
- Docker (con Compose) en tu ordenador, o Traefik v3 como binario.
- Cliente OpenSSH (
ssh); viene en macOS, Linux y Windows 10+. - Tu aplicación escuchando en un puerto local (p. ej.
3333). - El binario vault de HashiCorp (
vault version) para pedir tu certificado. - Tu cuenta de Keycloak del campus (la misma con la que entras al resto de la plataforma).
- Salida a Internet hacia
35.255.164.51puerto 2223 (SSH) y haciavault.alumnos.codecrypto.academy(HTTPS). Nada más. - Tu id de alumno (
[a-z][a-z0-9]{2,19}), dado de alta por el profesor en la lista del relay. - El equipo encendido y el túnel abierto mientras quieras ser visible.
Lo que NO necesitas
- IP pública, ni abrir puertos en tu router.
- Un dominio propio, ni DNS que configurar.
- Generar el certificado a mano: lo pide tu Traefik solo.
Qué intercambias con el profesor
| Tú entregas | Nada. Ya no envías claves: tu clave privada se crea y se queda en tu máquina; Vault solo firma la pública. |
|---|---|
| Tú recibes | Tu id en la lista del relay (lo añade el profesor) y el host del túnel: 35.255.164.51 puerto 2223. |
| Tu identidad | Tu usuario de Keycloak. Vault te firma un certificado SSH de 8 horas cuyo principal es al_<id>. Sin certificado vigente, el relay no te deja entrar. |
| Tus URLs | cualquier-cosa.usuario.alumnos.codecrypto.dev, todas por un túnel. |
| Reglas del nombre | Minúsculas, números y guiones; mínimo una etiqueta antes de tu usuario (lista.jviejo…). jviejo.alumnos… sin nada delante no vale. |
Cómo te identificas (sin enviar ninguna clave)
tu máquina ── ssh-keygen ───────────────► ~/.ssh/relay-vault (la privada NO sale de aquí) tu máquina ── login OIDC en el navegador ─► Keycloak ──► Vault (token con tu identidad) Vault ── firma relay-vault.pub ──────► certificado 8 h, principal al_<id> relay-sshd :2223 ── confía en la CA de Vault ──► acepta el certificado y abre tu túnel
Pasos
Pide tu certificado a Vault (con tu cuenta de Keycloak)
RELAY_USER=jviejo relay/alumno/relay-login.sh # crea ~/.ssh/relay-vault, abre Keycloak y guarda el certificado ssh-keygen -L -f ~/.ssh/relay-vault-cert.pub # debe mostrar Principals: al_jviejo y unas 8 h de validez
El script crea tu par de claves en tu máquina, hace el login OIDC en el navegador y pide a Vault (
https://vault.alumnos.codecrypto.academy) que firme la pública. Cambiajviejopor tu id.Configura el túnel en
~/.ssh/configHost relay-jviejo HostName 35.255.164.51 Port 2223 User al_jviejo IdentityFile ~/.ssh/relay-vault CertificateFile ~/.ssh/relay-vault-cert.pub IdentitiesOnly yes ServerAliveInterval 30 ServerAliveCountMax 3 ExitOnForwardFailure yes # socket en el servidor -> tu Traefik local RemoteForward /var/lib/alumnos/jviejo/web.sock 127.0.0.1:18443Esa línea
RemoteForwardes el-Rde ssh: el servidor crea el socket y lo entrega a tu puerto18443. Ojo: el usuario SSH lleva prefijo (al_jviejo); el directorio del socket usa tu id sin prefijo.Comprueba la clave del servidor (solo la primera vez)
ssh-keyscan -p 2223 -t ed25519 35.255.164.51 | ssh-keygen -lf - # la huella debe ser: SHA256:OSkYUTIx9Wdp6B3dhlbBlw7dxVg9jN5cxPWkQYFubSs ssh-keyscan -p 2223 -t ed25519 35.255.164.51 >> ~/.ssh/known_hosts # solo si coincide
Si te lo saltas, ssh dice
Host key verification failed.Levanta tu Traefik (el «borde»)
Copia la carpeta
relay/alumno/edge/(docker-compose.yml,traefik.yml,dynamic.yml) y descríbela así. Una ruta por cada nombre que quieras publicar:# dynamic.yml http: routers: miapp: rule: Host(`miapp.jviejo.alumnos.codecrypto.dev`) entryPoints: [websecure] tls: certResolver: le # certificado de Let's Encrypt automático service: miapp services: miapp: loadBalancer: servers: - url: "http://host.docker.internal:3333" # tu app fuera de Docker # - url: "http://mi-contenedor:80" # o un contenedor del mismo composedocker compose up -d # tras cambiar dynamic.yml: docker restart alumno-edge-traefik
Abre el túnel
ssh -N relay-jviejo # déjalo abierto
La primera vez, tu Traefik pide el certificado a Let's Encrypt a través de ese mismo túnel: tarda unos segundos.
Comprueba desde fuera
curl -sv https://miapp.jviejo.alumnos.codecrypto.dev/ -o /dev/null
Debes ver un certificado de Let's Encrypt para tu nombre y un
HTTP 200.Mantenlo vivo y renueva el certificado
RELAY_USER=jviejo relay/alumno/relay-login.sh --tunel
El certificado dura 8 horas. Con
--tunelse renueva solo antes de caducar (puede volver a abrir Keycloak en el navegador) y, si el túnel se corta, reconecta con una espera aleatoria.autosshreconecta, pero no renueva el certificado.
python3 -m http.server sirve todo el directorio donde lo lances, incluido .git y ficheros con claves. Usa --directory sobre una carpeta pensada para publicarse.
Si algo falla
| Lo que ves | Causa más probable | Solución |
|---|---|---|
ERR_CERT_COMMON_NAME_INVALID | Llega a tu Traefik pero no tiene ruta para ese nombre. | Añade el router con Host(...) y reinicia el borde. |
remote port forwarding failed for listen path | Ya hay otro túnel tuyo abierto, o tu id no está en la lista del relay. | Cierra el otro ssh; confirma tu id con el profesor. |
| La conexión se corta sin respuesta | El túnel no está abierto (no hay socket). | Lanza ssh -N relay-jviejo. |
| Certificado de «TRAEFIK DEFAULT CERT» | Tu Traefik no tiene (todavía) certificado para ese nombre. | Revisa docker logs alumno-edge-traefik; el túnel debe estar abierto para validar. |
404 page not found | Tu Traefik no reconoce el host de la petición. | El Host() debe coincidir exactamente con el nombre usado. |
502 Bad Gateway desde tu Traefik | Tu app no escucha o escucha solo en 127.0.0.1 y el borde corre en Docker. | Escucha en 0.0.0.0 o usa un contenedor en la misma red. |
Permission denied (publickey) | El certificado caducó (dura 8 h), tu id aún no está en la lista del relay, o su principal no es al_<id>. | Vuelve a ejecutar relay-login.sh; revisa ssh-keygen -L -f ~/.ssh/relay-vault-cert.pub; pide al profesor que te añada. |
Host key verification failed | Aún no has registrado la clave del servidor del puerto 2223. | Haz el paso de la huella (arriba) y compara el SHA256. |
Connection timed out / refused al puerto 2223 | Tu red bloquea la salida al 2223. | Prueba desde otra red y avisa al profesor. |
permission denied al pedir el certificado | Tu cuenta de Keycloak no pertenece al grupo de alumnos con permiso en Vault. | Avisa al profesor. |
Administración
En el servidor (ssh jose@35.255.164.51, con sudo). Ficheros: /opt/platform/relay-alumnos (nginx) y /opt/platform/relay-sshd (sshd en contenedor, puerto 2223).
Alta y baja
# alta: añade el id; en ≤ 60 s se crea la cuenta al_jviejo y su directorio (sin reiniciar nada) echo jviejo | sudo tee -a /opt/platform/relay-sshd/conf/alumnos.txt # baja: quita el id; en ≤ 60 s se borran cuenta, sesión y sockets sudo sed -i '/^jviejo$/d' /opt/platform/relay-sshd/conf/alumnos.txt # forzar la sincronización ahora docker exec relay-sshd relay-sync.sh
Ya no se registran claves: el alumno entra con su certificado de Vault. relay-sync.sh valida el id ([a-z][a-z0-9]{2,19}, sin nombres reservados) y una lista vacía no borra a nadie. Pendiente: que un job genere este fichero desde el grupo de alumnos de Keycloak.
Quién está conectado y qué pasa
# túneles abiertos (un socket por alumno, dentro del contenedor) docker exec relay-sshd sh -c 'ls -l /var/lib/alumnos/*/web.sock' # tráfico real: SNI, destino, bytes y duración docker logs nginx-alumnos --since 10m 2>&1 | grep -v 'sni=-' # autenticaciones: certificado, ID de Vault y CA docker logs relay-sshd --since 10m 2>&1 | grep 'Accepted certificate'
Las líneas con sni=- son el healthcheck del contenedor, no tráfico.
Piezas instaladas y su configuración
| sshd | /opt/platform/relay-sshd/ | Contenedor relay-sshd (Alpine, OpenSSH 9.9, puerto 2223): solo certificados de la CA de Vault, sin shell, AllowTcpForwarding remote + PermitListen 127.0.0.1:1, PerSourcePenalties no (evita bloquear una NAT entera), cap_drop: ALL + 8 capacidades (incluida FSETID). |
| nginx | /opt/platform/relay-alumnos/nginx/nginx.conf | stream + ssl_preread; el map elige /var/lib/alumnos/$alumno/web.sock. Lee el volumen relay-sockets, compartido con relay-sshd. |
| Traefik | /opt/platform/traefik/dynamic.yml | Bloque tcp: con el router alumnos (passthrough). Copias: .bak-relay, .bak-wildcard. |
| Identidad | /opt/platform/relay-sshd/conf/ca.pub | CA SSH de Vault (la misma del bastión): el principal del certificado debe ser al_<id>. Validez de 8 h; sin authorized_keys (AuthorizedKeysFile none). |
El sshd del host (puerto 22) con 50-alumnos.conf sigue instalado como respaldo del camino antiguo y se puede retirar.
*.alumnos.codecrypto.academy) siguen por sus routers. La regex del relay se comprobó contra los 111 nombres reales sin ninguna coincidencia.Escalabilidad
Qué aguanta hoy, qué se rompe primero y por dónde crecer. Las cifras marcadas medido salen de este servidor; las estimado son extrapolaciones lineales a partir de un solo túnel, no pruebas de carga.
Capacidad estimada solo del relay
| Alumnos con túnel abierto | RAM de sshd (cota alta) | Qué más pesa |
|---|---|---|
| 100 | ≤ 0,3 GB estimado | Nada relevante. |
| 500 | ≤ 1,6 GB estimado | Tormentas de reconexión (ver abajo). |
| 1 000 | ≤ 3,3 GB estimado | Comparte el servidor con la plataforma: ancho de banda y un único punto de fallo. |
La cota sale de multiplicar la medición de un túnel, que incluye la base fija del contenedor, así que sobrestima. En una prueba local el contenedor creó 1000 cuentas en ≈ 20 s y las borró en ≈ 6 s, con ≈ 5 MiB medido en local. Lo que no se ha probado es 1000 túneles simultáneos.
El servidor no descifra TLS (passthrough), así que casi no gasta CPU: solo copia bytes y mantiene el cifrado SSH. Cada petición cruza la red del servidor dos veces (entra por 443 y sale por el túnel, y lo mismo en la respuesta), de modo que el ancho de banda consumido es ≈ 2× la carga útil.
Qué se rompe primero (por orden)
| # | Cuello de botella | Por qué | Remedio |
|---|---|---|---|
| 1 | Límites de Let's Encrypt | Hay un tope semanal de certificados nuevos por dominio registrado (codecrypto.dev, común a todos los alumnos; unos 50 por semana, verifica el valor vigente). Cada nombre nuevo es un certificado. Las renovaciones no cuentan. | (a) Pedir ampliación a Let's Encrypt. (b) Registrar alumnos.codecrypto.dev en la Public Suffix List: cada usuario.alumnos… pasa a ser su propio dominio. (c) Un comodín por alumno con DNS-01 delegado (p. ej. acme-dns): 1 certificado por alumno y no por proyecto. (d) Otra CA ACME (ZeroSSL, Google Trust Services). |
| 2 | Tormenta de reconexión | Tras un corte, cientos de túneles reconectan a la vez. relay-sshd ya lleva MaxStartups 200:30:600 y PerSourcePenalties no medido (en sshd ≥ 9.8, por defecto, unos pocos fallos desde la NAT de un centro bloquean a toda la clase). Sin probar con 1000 reconexiones reales. | relay-login.sh --tunel ya reconecta con espera aleatoria. El bastión actual sigue con MaxStartups 10:30:60 y penalizaciones por IP activas: mismo riesgo. |
| 3 | Alta de alumnos | Claves resueltas: certificados SSH de 8 h firmados por Vault (ssh/sign/alumno), sin authorized_keys. Falta automatizar las cuentas: alumnos.txt se edita a mano. | Un job que lea el grupo de alumnos de Keycloak y regenere alumnos.txt (el relay ya sincroniza solo y no corta túneles). Y un rol de Vault propio del relay, con el principal por plantilla. |
| 4 | Un solo servidor | Es punto único de fallo y el ancho de banda de la VM es compartido con toda la plataforma. | Repartir alumnos en varios nodos de relay: una capa L4 delante con un map usuario → nodo (el socket vive en el nodo donde el alumno abrió el túnel) o una zona de DNS por grupo. |
| 5 | Abuso y cuotas | Cada alumno publica lo que corre en su máquina y no hay límite por alumno. Un límite de conexiones por nombre no es viable: el SNI aún no existe cuando nginx aplica limit_conn. | Limitar ancho de banda en stream (proxy_download_rate / proxy_upload_rate) y recursos del usuario con un slice de systemd. Para limitar por visitante hay que activar PROXY protocol (hoy nginx solo ve la IP de Traefik). |
| 6 | Visibilidad | No hay métricas por alumno. | El log de nginx ya incluye SNI, bytes y duración: enviarlo a la pila de observabilidad que ya tienes (/opt/platform/observability) y sacar bytes por alumno y nº de túneles activos. |
Hoja de ruta
- Lo que hay hoy (sshd en contenedor y certificados de Vault), más el email de contacto de ACME.
- Job Keycloak →
alumnos.txt. - Rol de Vault propio del relay.
- Decidir ya la estrategia de certificados (límite nº 1).
- Prueba de carga: 100 túneles concurrentes y una reconexión masiva.
- Public Suffix List o comodín por alumno.
- PROXY protocol y límites de ancho de banda.
- Métricas y alertas por alumno.
- Varios nodos de relay con enrutado
usuario → nodo. - Alta automatizada desde la plataforma del campus.
- Pruebas de carga reales antes de cada curso.