changes

docs-es/v2.0/libreqos-backend-architecture-es.md

@@ -242,6 +242,7 @@ Efecto práctico:
 |---|---|---|---|
 | Cambio solo de IP de circuito | Sí | No | Actualización de mapeo puede aplicarse sin reconstruir árbol |
 | Cambio de velocidad de circuito/sitio (subconjunto) | Sí | A veces | Depende del impacto estructural y class handles disponibles |
+| Virtualización runtime de nodos TreeGuard (subárbol soportado / ruta de rebalanceo top-level) | Sí | No | Bakery ahora la aplica como un plan runtime vivo: nodos no top-level usan reparent/prune/restore, y nodos top-level soportados usan una ruta de rebalanceo y migración entre colas |
 | Cambios masivos en todos los circuitos | A veces | Frecuente | Límites de escala y cardinalidad de transacciones |
 | Re-parent/reestructura topológica | Rara vez | Sí | Restricciones de mutación de subárbol HTB |
 | Alta/baja de circuitos | Sí (pequeño/mediano) | A veces | Límites de handles y fronteras de corrección en el diff |
@@ -269,6 +270,15 @@ flowchart TD
 3. Esperar mayor riesgo cuando coinciden muchos circuitos y muchos cambios estructurales.
 4. Diseñar la cadencia operativa para priorizar cambios incrementalmente seguros.
 
+### 7.4 Guardrails de seguridad para recargas completas
+
+Las recargas completas actuales de Bakery aplican dos verificaciones conservadoras de seguridad antes y durante reconstrucciones grandes de colas:
+
+1. Un preflight de qdisc estima los qdisc planificados por interfaz y además separa qdisc de infraestructura, hojas `cake` y hojas `fq_codel`.
+2. Ese mismo preflight aplica una proyección conservadora de memoria y bloquea de forma estricta las recargas completas claramente inseguras antes de arrancar `tc -batch`.
+3. Durante la aplicación chunked de una recarga completa, Bakery vuelve a revisar la memoria del host en los límites de chunk y aborta el resto de la aplicación si la memoria disponible cae por debajo de su piso de seguridad.
+4. Estos guardrails están sesgados intencionalmente hacia falsos positivos en recargas grandes para fallar temprano con diagnósticos en lugar de entrar en una espiral OOM.
+
 ## 8) Límites de Diseño para Operadores
 
 ### 8.1 Límites de observabilidad

docs-es/v2.0/node-manager-ui-es.md

@@ -9,6 +9,7 @@ Esta página documenta las vistas clave de la WebUI (Node Manager) y su comporta
 - El contenido puede variar según versión y funciones habilitadas.
 - Executive Summary ofrece una vista operativa compacta para redes grandes, con páginas de detalle para heatmaps y rankings ejecutivos.
 - Bakery ofrece una pestaña dedicada para el estado de aplicación de colas, eventos recientes de Bakery, resultados de seguridad/preflight de qdisc y el gráfico existente de actividad de circuitos.
+- El preflight de qdisc de Bakery ahora presenta los qdisc planificados por interfaz como barras compactas de uso con badges del tipo de qdisc, además de una tabla separada de límites/memoria para presupuesto seguro, límite del kernel, memoria estimada de qdisc, memoria disponible actual y margen sobre el piso de seguridad.
 - Algunos gráficos pueden tardar un poco en poblarse al abrir una pestaña por primera vez, especialmente en sistemas ocupados o inmediatamente después de reiniciar servicios.
 - Durante un full reload de Bakery, las tarjetas de conteo de colas mantienen los últimos valores conocidos de HTB/CAKE/fq-codel y los marcan como `Reloading` en lugar de mostrar ceros momentáneamente.
 

docs-es/v2.0/treeguard-es.md

@@ -32,11 +32,19 @@ TreeGuard evalúa utilización, frescura de RTT, guardrails de CPU y guardrails
 Comportamiento de alto nivel:
 
 1. Bajo condiciones sostenidas de baja carga, TreeGuard puede cambiar una dirección de `cake` a `fq_codel`.
-2. Si sube la utilización, los guardrails RTT/QoO no son seguros o se cumplen condiciones de reversión, TreeGuard vuelve a `cake`.
+2. Si sube la utilización, los guardrails de QoO no son seguros o se cumplen condiciones de reversión, TreeGuard vuelve hacia la política SQM base del circuito.
 3. Las decisiones pueden ser independientes por dirección cuando `independent_directions = true`.
 
 Esto crea un perfil dinámico en el que direcciones cargadas favorecen `cake diffserv4`, mientras direcciones de baja carga pueden usar `fq_codel` cuando las condiciones son seguras.
 
+La política SQM base proviene de la intención del operador, no de defaults internos de TreeGuard. En la práctica, TreeGuard parte de la política efectiva configurada para cada circuito y solo persiste su propio overlay temporal cuando necesita diferir de esa base.
+
+Regla importante de política base:
+
+1. Si la política SQM base de una dirección es `cake`, TreeGuard puede cambiar temporalmente esa dirección a `fq_codel` y luego volver a la base.
+2. Si la política SQM base de una dirección es `fq_codel`, TreeGuard no conmuta esa dirección de circuito hacia `cake`.
+3. La virtualización de enlaces sigue disponible independientemente de la política SQM base del circuito.
+
 ## Configuración (`/etc/lqos.conf`)
 
 La configuración de TreeGuard vive bajo `[treeguard]` y sus sub-secciones:
@@ -80,20 +88,38 @@ enabled = true
 
 ## Overrides y Notas Operativas
 
-Cuando está habilitado y no está en dry-run, TreeGuard puede persistir decisiones en:
+Cuando está habilitado y no está en dry-run, TreeGuard puede persistir decisiones SQM de circuitos en:
 
 - `lqos_overrides.treeguard.json`
 
 TreeGuard está diseñado para no pelear con overrides del operador. Si existen overrides del operador para entidades enroladas, TreeGuard omite esas entidades y reporta advertencias.
 
-Las decisiones de virtualización de nodos de TreeGuard son overrides de tiempo de ejecución. El
-scheduler no las materializa de vuelta en el `network.json` base, por lo que deshabilitar o limpiar
-TreeGuard no reescribe permanentemente la topología definida por el operador.
+Las decisiones de virtualización de nodos de TreeGuard son operaciones de Bakery solo en tiempo de
+ejecución. El scheduler no las materializa de vuelta en el `network.json` base, y tampoco se
+persisten como entradas TreeGuard `set_node_virtual` dentro de la entrada efectiva de shaping. En
+v1 son efímeras: un reinicio del daemon devuelve el árbol físico a la topología base definida por
+el operador hasta que TreeGuard vuelva a decidir.
 
-TreeGuard también se niega a gestionar nodos que ya estén marcados con `"virtual": true` en el `network.json` base. Si existen overrides viejos de TreeGuard para esos nodos, TreeGuard limpia su propia capa de overrides y vuelve a respetar la definición base de la topología.
+Las decisiones SQM por circuito de TreeGuard también son overrides de tiempo de ejecución. El scheduler no materializa los cambios SQM propiedad de TreeGuard de vuelta en el `ShapedDevices.csv` base, por lo que limpiar TreeGuard no reescribe permanentemente la política SQM definida por el operador.
+
+TreeGuard también se niega a gestionar nodos que ya estén marcados con `"virtual": true` en el `network.json` base. Si existen overrides legados de TreeGuard para esos nodos, TreeGuard limpia ese estado legado y vuelve a respetar la definición base de la topología.
 
 Para la gestión SQM por circuito, TreeGuard trata los valores duplicados de `device_id` como colisiones de identidad inseguras. Si el mismo `device_id` aparece en más de un circuito dentro de `ShapedDevices.csv`, TreeGuard omite esos circuitos afectados y limpia cualquier override SQM de TreeGuard asociado a esos `device_id` duplicados.
 
+Si la telemetría RTT no está disponible temporalmente después de un reinicio, TreeGuard no trata la ausencia de RTT por sí sola como evidencia para revertir direcciones en `fq_codel`. Siguen aplicando otros guardrails como utilización, QoO y presión de CPU.
+
+TreeGuard también aplica un presupuesto global conservador de cambios SQM por tick. En poblaciones muy grandes de circuitos enrolados, los cambios SQM excedentes se difieren a ticks posteriores en lugar de saturar Bakery en una sola pasada.
+
+Para escalar mejor, TreeGuard ya no reconstruye la membresía de circuitos desde `ShapedDevices.csv` en cada tick de circuitos. Ahora mantiene un inventario por circuito en caché derivado de `ShapedDevices.csv`, lee la telemetría viva por circuito desde el snapshot compartido de rollup por circuito actualizado una vez por segundo, y reparte las evaluaciones SQM grandes con `all_circuits = true` a lo largo de múltiples ticks en lugar de reescanear todos los circuitos enrolados cada segundo.
+
+En la práctica esto significa:
+
+1. La virtualización de enlaces sigue la cadencia normal de ticks de TreeGuard.
+2. La evaluación SQM de circuitos para enrolamientos pequeños sigue completándose rápidamente.
+3. Los enrolamientos muy grandes con `all_circuits` se recorren de forma incremental a lo largo de varios ticks, con un objetivo de barrido completo de alrededor de 15 segundos en vez de intentar un escaneo completo por segundo.
+4. La virtualización de nodos de TreeGuard ahora usa rutas vivas de planificación/aplicación en Bakery en lugar de forzar una recarga completa de LibreQoS o de Bakery.
+5. La virtualización runtime soportada de nodos top-level ahora usa un plan de rebalanceo/migración en Bakery que puede promover sitios hijos y circuitos directos entre raíces de cola, preservando la jerarquía lógica para reportes.
+
 La actividad reciente de TreeGuard está disponible en dos lugares:
 
 - Las vistas de estado/actividad de TreeGuard en la WebUI.

docs-es/v2.0/troubleshooting-es.md

@@ -46,14 +46,17 @@ Incluya también:
 
 ### La contraseña de usuario no funciona
 
-Elimine el archivo de usuarios:
+Los builds actuales:
+- migran automáticamente archivos de autenticación antiguos
+- redirigen `/login.html` a `/first-run.html` cuando no existen usuarios
 
 ```bash
-sudo rm /opt/libreqos/src/lqusers.toml
-sudo systemctl restart lqosd lqos_scheduler
+sudo systemctl restart lqosd
 ```
 
-Luego abra: `IP_CAJA:9123/index.html`.
+Si el usuario/contraseña correctos siguen fallando, pruebe primero con ese reinicio.
+
+Elimine `lqusers.toml` solo si desea reiniciar el acceso o si el archivo está corrupto y no se puede reparar. Después de eliminarlo, reinicie `lqosd` y abra `IP_CAJA:9123/login.html`; la WebUI debería redirigirlo automáticamente al flujo de primer inicio.
 
 ### No hay WebUI en x.x.x.x:9123
 
@@ -216,7 +219,8 @@ WebUI muestra códigos legibles por máquina para triage rápido.
 |---|---|---|---|
 | `MAPPED_CIRCUIT_LIMIT` | Bakery está forzando límite de circuitos mapeados. | Estado de licencia Insight y `journalctl -u lqosd` con requested/allowed/dropped. | Reducir circuitos mapeados o actualizar licencia/límites. |
 | `TC_U16_OVERFLOW` | IDs minor de clases/colas excedieron rango u16 de tc en una cola CPU. | `journalctl -u lqos_scheduler -u lqosd`, profundidad topológica y distribución por colas. | Aumentar paralelismo de colas y/o simplificar/rebalancear jerarquía. |
-| `TC_QDISC_CAPACITY` | Los qdisc autoasignados planificados exceden el presupuesto seguro por interfaz antes de aplicar. | Conteos estimados de qdisc por interfaz en el contexto del urgent issue, `journalctl -u lqos_scheduler -u lqosd`, configuración `on_a_stick` y `monitor_only`. | Reducir la carga planificada de qdisc para esta ejecución (por ejemplo menos circuitos/dispositivos en la forma de prueba) antes de reintentar; no confiar en una aplicación parcial. |
+| `TC_QDISC_CAPACITY` | Los qdisc autoasignados planificados exceden el presupuesto seguro por interfaz o el preflight conservador de seguridad de memoria de Bakery antes de aplicar. | Conteos estimados por interfaz, desglose por tipo de qdisc y campos de memoria en el contexto del urgent issue, `journalctl -u lqos_scheduler -u lqosd`, configuración `on_a_stick` y `monitor_only`. | Reducir la carga planificada de qdisc para esta ejecución (por ejemplo menos circuitos/dispositivos en la forma de prueba) antes de reintentar; no confiar en una aplicación parcial. |
+| `BAKERY_MEMORY_GUARD` | Un full reload chunked de Bakery fue detenido a mitad de aplicación porque la memoria disponible del host cayó por debajo del piso de seguridad. | `journalctl -u lqosd`, memoria disponible/total en el contexto del urgent issue y progreso reciente de aplicación de Bakery. | Tratar la ejecución como fallida, reducir presión de memoria o huella de colas y reintentar solo cuando el host esté estable. |
 | `XDP_IP_MAPPING_CAPACITY` | Los mapeos IP requeridos exceden la capacidad actual del mapa XDP en el kernel. | Forma de `ShapedDevices.csv`, mezcla IPv4/IPv6, supuesto de un dispositivo frente a varios dispositivos, `journalctl -u lqos_scheduler -u lqosd`. | Reducir mapeos requeridos de inmediato (por ejemplo menos dispositivos o prueba IPv4-only), o aumentar la capacidad del mapa del kernel en un cambio coordinado. |
 | `XDP_IP_MAPPING_APPLY_FAILED` | Uno o más inserts de mapeo IP fallaron durante la aplicación. | `journalctl -u lqos_scheduler -u lqosd` para ejemplos resumidos y conteos de fallo. | Corregir la causa del fallo y volver a ejecutar; no confiar en shaping parcial. |