Circuito de la información
Relay de alumnos · *.alumnos.codecrypto.dev

Cómo llega una petición desde cualquier navegador hasta la aplicación que un alumno tiene en su propio ordenador, sin que el alumno tenga IP pública, abra puertos ni gestione certificados a mano.

Servidor alumnos-vm · 35.255.164.51 relay-sshd · Alpine · OpenSSH 9.9 · :2223 Traefik 3.7 · nginx 1.27 Identidad Keycloak → Vault · certificado SSH 8 h Ejemplo https://lista.jviejo.alumnos.codecrypto.dev

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

—
SERVIDOR alumnos-vm · 35.255.164.51 · GCP e2-standard-8 MÁQUINA DEL ALUMNO · detrás de NAT · sin IP pública INTERNET IDENTIDAD · alumnos-vm · Keycloak + Vault
TLS de punta a punta (visitante ⇄ Traefik del alumno) Dentro del túnel SSH (segunda capa de cifrado) HTTP plano, solo en localhost del alumno Identidad: login OIDC en Keycloak y certificado firmado por Vault
—

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.

#ComponenteDónde / IP / puertoQué haceComprobar 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.51 puerto 2223 (SSH) y hacia vault.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ú entregasNada. Ya no envías claves: tu clave privada se crea y se queda en tu máquina; Vault solo firma la pública.
Tú recibesTu id en la lista del relay (lo añade el profesor) y el host del túnel: 35.255.164.51 puerto 2223.
Tu identidadTu 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 URLscualquier-cosa.usuario.alumnos.codecrypto.dev, todas por un túnel.
Reglas del nombreMinú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

  1. 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. Cambia jviejo por tu id.

  2. Configura el túnel en ~/.ssh/config

    Host 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:18443

    Esa línea RemoteForward es el -R de ssh: el servidor crea el socket y lo entrega a tu puerto 18443. Ojo: el usuario SSH lleva prefijo (al_jviejo); el directorio del socket usa tu id sin prefijo.

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

  4. 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 compose
    docker compose up -d                 # tras cambiar dynamic.yml:  docker restart alumno-edge-traefik
  5. 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.

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

  7. Mantenlo vivo y renueva el certificado

    RELAY_USER=jviejo relay/alumno/relay-login.sh --tunel

    El certificado dura 8 horas. Con --tunel se 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. autossh reconecta, pero no renueva el certificado.

Lo que publiques es público. Cualquiera con el nombre puede entrar (y los nombres con certificado quedan en los registros públicos de Certificate Transparency). No expongas carpetas completas: 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 vesCausa más probableSolución
ERR_CERT_COMMON_NAME_INVALIDLlega 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 pathYa 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 respuestaEl 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 foundTu Traefik no reconoce el host de la petición.El Host() debe coincidir exactamente con el nombre usado.
502 Bad Gateway desde tu TraefikTu 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 failedAú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 2223Tu red bloquea la salida al 2223.Prueba desde otra red y avisa al profesor.
permission denied al pedir el certificadoTu 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.confstream + 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.ymlBloque tcp: con el router alumnos (passthrough). Copias: .bak-relay, .bak-wildcard.
Identidad/opt/platform/relay-sshd/conf/ca.pubCA 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.

No toca lo existente. Los proyectos de la plataforma (*.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.

3,3 MiB
RAM del contenedor relay-sshd entero con 1 túnel (6 procesos) medido
17,6 MiB
nginx-alumnos entero, 9 procesos, 0 % CPU medido
18 GB libres
de 32 GB (8 vCPU), con 113 contenedores ya en marcha medido

Capacidad estimada solo del relay

Alumnos con túnel abiertoRAM de sshd (cota alta)Qué más pesa
100≤ 0,3 GB estimadoNada relevante.
500≤ 1,6 GB estimadoTormentas de reconexión (ver abajo).
1 000≤ 3,3 GB estimadoComparte 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 botellaPor quéRemedio
1Límites de Let's EncryptHay 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).
2Tormenta de reconexiónTras 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.
3Alta de alumnosClaves 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.
4Un solo servidorEs 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.
5Abuso y cuotasCada 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).
6VisibilidadNo 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

Fase 1 · hasta ~100 alumnos
  • 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).
Fase 2 · 100–500
  • 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.
Fase 3 · 500+
  • Varios nodos de relay con enrutado usuario → nodo.
  • Alta automatizada desde la plataforma del campus.
  • Pruebas de carga reales antes de cada curso.
Lo que no está medido. No se ha hecho ninguna prueba de carga: las cifras de capacidad son extrapolaciones de un solo túnel (cota alta). Antes de abrirlo a una clase completa conviene simular, por ejemplo, 100 túneles concurrentes y una reconexión simultánea.