diff --git a/docs-es/index.rst b/docs-es/index.rst index a5ce3b0e..dec7226a 100644 --- a/docs-es/index.rst +++ b/docs-es/index.rst @@ -26,6 +26,7 @@ Bienvenido a la documentación de LibreQoS v2.0/components-es v2.0/node-manager-ui-es v2.0/stormguard-es + v2.0/treeguard-es v2.0/high-availability-es v2.0/scale-topology-es v2.0/recipes-es @@ -46,6 +47,7 @@ Bienvenido a la documentación de LibreQoS :caption: Misceláneo v2.0/libreqos-backend-architecture-es + v2.0/htb_fq_codel_cake-es v2.0/cake-es v2.0/performance-tuning-es v2.0/extras-es diff --git a/docs-es/v2.0/configuration-advanced-es.md b/docs-es/v2.0/configuration-advanced-es.md index 6194eb9a..15f05e1f 100644 --- a/docs-es/v2.0/configuration-advanced-es.md +++ b/docs-es/v2.0/configuration-advanced-es.md @@ -189,6 +189,16 @@ A continuación un ejemplo de entrada en ShapedDevices.csv: Si está utilizando una de nuestras integraciones con CRM, este archivo se generará automáticamente. Si no está utilizando una integración, puede editar el archivo manualmente usando la interfaz WebUI o editando directamente el archivo ShapedDevices.csv a través de la CLI. +#### TreeGuard y SQM por circuito (función próxima) + +TreeGuard es una función próxima de v2.0 que puede ajustar dinámicamente el SQM por circuito (`cake`/`fq_codel`) según condiciones del circuito. + +Importante: +- TreeGuard no está habilitado por defecto. +- El comportamiento por defecto de LibreQoS se mantiene en su SQM configurado/global a menos que habilite TreeGuard explícitamente. + +Consulte [TreeGuard (Función Próxima de v2.0)](treeguard-es.md). + #### Múltiples IPs por Circuito Si necesita listar múltiples IPv4 en el campo IPv4, o múltiples IPv6 en el campo IPv6, agregue una coma entre ellas. Si está editando con un editor CSV (LibreOffice Calc, Excel), el editor CSV automáticamente colocará comillas alrededor de los elementos separados por coma. Si usted está editando el archivo manualmente con un editor de texto como notepad o nano, por favor agregue comillas alrededor de las entradas separadas por coma. diff --git a/docs-es/v2.0/htb_fq_codel_cake-es.md b/docs-es/v2.0/htb_fq_codel_cake-es.md new file mode 100644 index 00000000..e27ea158 --- /dev/null +++ b/docs-es/v2.0/htb_fq_codel_cake-es.md @@ -0,0 +1,416 @@ +# HTB + fq_codel + CAKE: Comportamiento Detallado de Colas en LibreQoS + +Esta página es el complemento de análisis profundo de colas para [Arquitectura Backend de LibreQoS](libreqos-backend-architecture-es.md). + +Explica: + +1. Por qué LibreQoS combina `HTB` con qdiscs hoja (`fq_codel` o `CAKE`) +2. Cómo funciona `fq_codel` en la práctica +3. Cómo funciona `CAKE` en la práctica +4. Cuándo elegir `fq_codel` vs `CAKE` +5. Patrones de observabilidad y troubleshooting para operadores + +## 1) Por Qué Existen Estos Tres Componentes Juntos + +En LibreQoS en producción: + +1. `HTB` entrega política jerárquica de tasa (`rate`, `ceil`, préstamo, jerarquía) +2. `fq_codel` o `CAKE` entrega servicio de cola por flujo y AQM dentro de cada envolvente moldeada + +Esta separación es intencional: + +- Problema de política: "¿Cuánto puede enviar esta clase?" -> `HTB` +- Problema de cola: "¿Qué paquete sale después mientras se controla latencia?" -> `fq_codel`/`CAKE` + +## 2) Ubicación en Tiempo de Ejecución en LibreQoS + +Conceptualmente, los paquetes pasan por: + +1. raíz `mq` +2. jerarquía `HTB` +3. qdisc hoja por clase moldeada (`CAKE` por defecto, `fq_codel` opcional) + +Operativamente, suele ser: + +`mq` raíz -> padres HTB por CPU -> clases HTB por circuito -> qdisc hoja (`cake diffserv4` o `fq_codel`) + +Cada clase HTB tiene un punto de acople para qdisc hijo. Si no hay qdisc hoja explícito, se usa el comportamiento de cola por defecto del kernel para esa clase. + +Modelo práctico de comportamiento en LibreQoS: + +1. La política por defecto de fábrica usa `HTB` + `cake diffserv4` para circuitos moldeados. +2. TreeGuard (función próxima) puede cambiar dinámicamente direcciones de circuito entre `cake diffserv4` y `fq_codel` según guardrails de baja carga/RTT. +3. TreeGuard no está habilitado por defecto. + +Consulte [TreeGuard (Función Próxima de v2.0)](treeguard-es.md) para detalles de configuración y despliegue. + +## 3) Resumen de HTB para Usuarios de AQM + +### 3.1 Mecánicas centrales de HTB + +1. Los tokens se consumen por bytes de paquete y se recargan con el tiempo. +2. `rate` define servicio garantizado. +3. `ceil` define el máximo prestable cuando existe capacidad en el padre. +4. Los hijos solo piden prestado de capacidad sobrante en ancestros. +5. La contención entre hermanos depende de `prio`, del scheduler y de la proporción de clases. + +### 3.2 Controles clave de HTB + +- `rate`, `ceil` +- `prio` +- `burst`, `cburst` +- `quantum`, `r2q` +- clase `default` (concepto Linux HTB; ver nota de comportamiento de LibreQoS) + +### 3.3 Por qué importa para `fq_codel` y `CAKE` + +`fq_codel` y `CAKE` no reemplazan jerarquía ni política de tasa de HTB. Gestionan servicio de cola dentro de la envolvente que HTB permite. + +### 3.4 Comportamiento de tráfico no definido en LibreQoS + +El comportamiento de LibreQoS es explícito: + +1. el tráfico no mapeado a un circuito moldeado pasa de largo (pass-through) +2. LibreQoS no dirige tráfico no definido a clases HTB `default` +3. el comportamiento de clase `default` de HTB sigue existiendo en Linux `tc`, pero no es la vía usada por LibreQoS para tráfico no definido + +Operativamente, esto implica que el troubleshooting de tráfico no definido comienza con validación de clasificación/mapeo, no con ajuste de clase `default`. + +### 3.5 Esqueleto compacto HTB (patrón de referencia) + +Patrón ilustrativo Linux HTB + qdisc hoja: + +```bash +tc qdisc add dev root handle 1: htb default 30 +tc class add dev parent 1: classid 1:1 htb rate 1gbit ceil 1gbit +tc class add dev parent 1:1 classid 1:10 htb rate 700mbit ceil 1gbit prio 1 +tc class add dev parent 1:1 classid 1:20 htb rate 300mbit ceil 1gbit prio 2 +tc class add dev parent 1:1 classid 1:30 htb rate 10mbit ceil 1gbit prio 7 +tc qdisc add dev parent 1:10 cake diffserv4 +tc qdisc add dev parent 1:20 fq_codel +tc qdisc add dev parent 1:30 cake diffserv4 +tc filter add dev protocol ip parent 1:0 prio 1 u32 match ip src /32 flowid 1:10 +tc filter add dev protocol ip parent 1:0 prio 2 u32 match ip src /32 flowid 1:20 +``` + +En LibreQoS, los comandos de colas/clases se generan automáticamente y el tráfico no definido pasa de largo en lugar de enviarse a una clase HTB `default`. + +## 4) Profundización en fq_codel + +### 4.1 Qué es fq_codel + +`fq_codel` combina: + +1. colas estocásticas por flujo (hash) +2. planificación de equidad estilo DRR entre colas +3. AQM CoDel por cola + +Referencias principales: + +- `tc-fq_codel(8)` +- RFC 8290 (Flow Queue CoDel) + +### 4.2 Comportamiento del scheduler y ventaja para flujos esporádicos + +FQ-CoDel mantiene listas activas de flujos "new" y "old". Las colas recién activadas se priorizan frente a colas persistentemente en backlog, lo que beneficia tráfico interactivo/esporádico. + +También utiliza crédito por bytes (`quantum`), por lo que la equidad es por bytes y no por cantidad de paquetes. + +### 4.3 Modelo de hash de flujos + +Por defecto, los paquetes se clasifican con hash de 5-tupla hacia un número configurable de buckets (`flows`). Colisiones de hash son posibles y forman parte del compromiso de las colas estocásticas. + +### 4.4 Parámetros de fq_codel que realmente se ajustan + +Parámetros útiles de `tc-fq_codel(8)`: + +1. `limit PACKETS`: tope duro de paquetes en cola (por defecto `10240`) +2. `memory_limit BYTES`: tope de memoria (por defecto `32MB`); se aplica el menor entre `limit` y memoria +3. `flows NUMBER`: buckets hash (por defecto `1024`, se define al crear) +4. `target TIME`: retardo mínimo persistente aceptable (por defecto `5ms`) +5. `interval TIME`: ventana de control CoDel; normalmente del orden del RTT peor en el cuello de botella (por defecto `100ms`) +6. `quantum BYTES`: quantum DRR (por defecto `1514`) +7. `ecn`/`noecn`: ECN encendido/apagado (`ecn` por defecto en fq_codel) +8. `ce_threshold TIME`: umbral de marcado ECN bajo para casos tipo DCTCP +9. `ce_threshold_selector VALUE/MASK`: aplica CE threshold solo al tráfico seleccionado +10. `drop_batch`: máximo lote de drops cuando se exceden límites (por defecto `64`) + +### 4.5 Observabilidad fq_codel (`tc -s qdisc show`) + +Campos comunes a revisar: + +1. `dropped`, `overlimits`, `requeues` +2. `drop_overlimit` +3. `new_flow_count` +4. `ecn_mark` +5. `new_flows_len`, `old_flows_len` +6. `backlog` + +Patrón de interpretación: + +1. Verifique que exista presión de cola (`backlog`, `requeues`, `overlimits`) +2. Verifique si AQM está actuando (`ecn_mark`, `dropped`) +3. Correlacione `new_flows_len`/`old_flows_len` con mezcla de tráfico (esporádico vs masivo) + +## 5) Profundización en CAKE + +### 5.1 Arquitectura de CAKE + +CAKE integra varias capas en un único qdisc: + +1. shaper en modo deficit +2. cola de prioridad (tins) +3. aislamiento de flujo (`DRR++`) +4. AQM (`COBALT`, combina CoDel + BLUE) +5. gestión de paquetes y compensación de overhead + +Referencias principales: + +- `tc-cake(8)` +- páginas CAKE y CakeTechnical de Bufferbloat +- paper Piece of CAKE (`cake.pdf`) + +### 5.2 Operación con shaping vs sin shaping + +Cuando se define `bandwidth`, el shaper de CAKE y su ajuste derivado gobiernan umbrales de tins y comportamiento temporal. + +Sin shaping (`unlimited`), CAKE aún aporta servicio de cola y lógica AQM, pero el servicio de tins ya no opera contra un objetivo fijo de cuello de botella moldeado. + +### 5.3 Modos de aislamiento de flujo + +CAKE soporta múltiples modos de equidad: + +1. `flowblind` (sin aislamiento por flujo) +2. `flows` (equidad por flujo de 5-tupla) +3. `srchost`, `dsthost`, `hosts` +4. `dual-srchost`, `dual-dsthost` +5. `triple-isolate` (valor por defecto en `tc-cake(8)`) + +Nota operativa: + +- `triple-isolate` es un valor seguro cuando se requiere control tanto por flujo como por host. + +### 5.4 Conciencia de NAT + +`nat`/`nonat` controla si CAKE hace lookup de NAT antes de aplicar aislamiento de flujo. + +Por qué importa: + +- Sin `nat`, la equidad ve solo direcciones post-NAT. +- Con `nat`, la equidad puede representar mejor hosts internos detrás de NAT (si NAT está en la misma ruta/caja). + +### 5.5 Modos DiffServ y tins + +Presets principales de prioridad: + +1. `besteffort` (un solo tin, sin cola de prioridad) +2. `diffserv3` +3. `diffserv4` +4. `diffserv8` +5. `precedence` (legado, desaconsejado en despliegues modernos) + +`tc-cake(8)` documenta actualmente `diffserv3` como default general, mientras que LibreQoS típicamente usa `cake diffserv4` como política por defecto de fábrica para operadores. + +### 5.6 Mapeo DSCP `diffserv4` en LibreQoS + +LibreQoS usa comúnmente CAKE con `diffserv4`. Mapeo práctico de clases: + +1. Sensible a latencia: `CS7`, `CS6`, `EF`, `VA`, `CS5`, `CS4` +2. Streaming multimedia: `AF4x`, `AF3x`, `CS3`, `AF2x`, `TOS4`, `CS2`, `TOS1` +3. Best Effort: `CS0`, `AF1x`, `TOS2` y codepoints no reconocidos +4. Tráfico de fondo: `CS1` + +Codepoints comunes en uso operativo: + +1. `CS1` (Least Effort) +2. `CS0` (Best Effort) +3. `TOS1` (Max Reliability / LLT "Lo") +4. `TOS2` (Max Throughput) +5. `TOS4` (Min Delay) +6. `TOS5` (LLT "La") +7. `AF1x` +8. `AF2x` +9. `AF3x` +10. `AF4x` +11. `CS2` +12. `CS3` +13. `CS4` +14. `CS5` +15. `CS6` +16. `CS7` +17. `VA` +18. `EF` + +Marco de clases de tráfico estilo RFC 4594 (alto nivel): + +1. Control de red: `CS6`, `CS7` +2. Telefonía: `EF`, `VA` +3. Señalización: `CS5` +4. Videoconferencia multimedia: `AF4x` +5. Interactivo en tiempo real: `CS4` +6. Streaming multimedia: `AF3x` +7. Video broadcast: `CS3` +8. Datos de baja latencia: `AF2x`, `TOS4` +9. Operaciones/administración/gestión: `CS2`, `TOS1` +10. Servicio estándar: `CS0` y codepoints no reconocidos +11. Datos de alto throughput: `AF1x`, `TOS2` +12. Datos de baja prioridad: `CS1` + +Nota para `fq_codel`: + +1. `fq_codel` no tiene modelo de tins de CAKE ni scheduler de clases DSCP estilo CAKE. +2. El marcado DSCP puede usarse por políticas externas de clasificación, pero no vía comportamiento de tins `diffserv4` de CAKE. +3. En LibreQoS, la prioridad DSCP descrita arriba aplica cuando se selecciona CAKE con `diffserv4`. + +### 5.7 Compensación de overhead y framing + +CAKE puede contabilizar overhead/framing de capa de enlace usando: + +1. `overhead N` +2. `mpu N` +3. `atm`, `ptm`, `noatm` +4. atajos (`ethernet`, `docsis`, etc.) +5. `raw` y `conservative` + +Regla operativa: + +- Si overhead/framing está mal, el shaping también estará mal. Valide con pruebas de tráfico realistas. + +### 5.8 Manejo de GSO (`split-gso`) + +Por defecto, CAKE divide superpaquetes GSO para reducir impacto de latencia en flujos competidores, especialmente a tasas bajas. + +En velocidades muy altas (ej. >10 Gbps), `no-split-gso` puede mejorar throughput pico, con posible costo en suavidad de latencia. + +### 5.9 Filtrado ACK + +CAKE soporta: + +1. `ack-filter` +2. `ack-filter-aggressive` +3. `no-ack-filter` (por defecto) + +El mejor caso de uso es enlace asimétrico donde ACKs en subida limitan el goodput de bajada. Aplíquelo con cautela y valide con tráfico real de aplicaciones, no solo pruebas sintéticas. + +### 5.10 Modo ingress y autorate + +`ingress` cambia contabilidad y ajuste para realidades de shaping en bajada (incluye contar paquetes descartados como datos ya transitados). + +`autorate-ingress` puede estimar capacidad desde el tráfico entrante y es útil principalmente en enlaces muy variables (por ejemplo algunos enlaces celulares). No puede estimar cuellos de botella que estén aguas abajo del punto donde se adjunta CAKE. + +### 5.11 Observabilidad CAKE (`tc -s qdisc show`) + +Campos útiles frecuentes: + +1. nivel superior: `dropped`, `overlimits`, `backlog`, `memory used`, `capacity estimate` +2. por tin: `thresh`, `target`, `interval` +3. telemetría de delay: `pk_delay`, `av_delay`, `sp_delay` +4. hashing: `way_inds`, `way_miss`, `way_cols` +5. señalización: `drops`, `marks` +6. filtrado ACK: `ack_drop` +7. actividad de cola: `sp_flows`, `bk_flows`, `un_flows`, `max_len`, `quantum` + +Patrón de interpretación: + +1. confirme que tins y umbrales coinciden con la política esperada +2. inspeccione EWMAs de delay por tin +3. correlacione `drops`/`marks` con latencia y throughput observados +4. monitoree indicadores de colisión hash (`way_cols`) bajo concurrencia alta + +## 6) Marco de Política en LibreQoS: CAKE vs fq_codel + +Para operadores LibreQoS, parta del comportamiento de plataforma: + +1. La operación por defecto es `cake diffserv4` en hojas de clase HTB. +2. TreeGuard (función próxima) puede mover direcciones seleccionadas de circuito a `fq_codel` durante baja carga sostenida y volver a `cake` cuando sube utilización o presión de guardrails. +3. Los overrides manuales por circuito con `sqm` siguen dando control explícito al operador. + +Use esta matriz para contexto de tradeoffs: + +| Dimensión | `fq_codel` | `CAKE` | +|---|---|---| +| Complejidad de configuración | Menor | Mayor (más funciones integradas) | +| Huella de recursos a escala | Usualmente menor | Usualmente mayor | +| Funciones de shaping integradas | No (requiere shaper padre como HTB) | Sí (shaper deficit-mode integrado) | +| Comportamiento DiffServ/tins | Básico/indirecto | Modelo de tins nativo robusto | +| Modos de aislamiento de host | No estilo CAKE | Modos ricos de aislamiento host/flujo | +| Compensación de overhead | Limitada | Controles ricos de framing/overhead | +| Optimización ACK en enlaces asimétricos | No | Sí (modos de ACK filtering) | +| Mejor encaje | Muchas colas con recursos ajustados | Tráfico mixto con prioridad en riqueza de política y suavidad | + +## 7) Notas Operativas de LibreQoS + +Desde pruebas de mantenedor y feedback de despliegue: + +1. `fq_codel` no tiene rate limiting intrínseco; depende de HTB para política de tasa. +2. `fq_codel` y `CAKE` mantienen tablas de estado por flujo, por lo que RAM/hash importan a gran escala. +3. `CAKE` y HTB son viables incluso en enlaces de tasa muy baja y asimétricos. +4. Un patrón de limitador tipo "sandwich" con HTB+fq_codel puede ser práctico en algunos entornos. +5. Algunas vistas de tráfico de dashboard reflejan contexto pre-drop; interprete contadores junto con semántica de drop/mark. +6. La frase "solo la saturación dura se beneficia de AQM" es demasiado estrecha; AQM y fair queueing pueden mejorar latencia bajo presión de cola (bursts/contención), incluso antes de que la interfaz esté al 100%. +7. Patrones históricos de cubeta compartida/default refuerzan que la dinámica de colas, y no solo "enlace completamente pegado", impulsa el valor de AQM; en LibreQoS actual, tráfico no definido es pass-through, así que aplique este principio a hojas HTB gestionadas. + +## 8) Flujo Práctico de Observabilidad + +Comience con: + +```bash +tc -s qdisc show dev +tc -s class show dev +``` + +Luego: + +1. confirme que existan clases HTB donde espera +2. confirme tipo de qdisc hoja (`cake` vs `fq_codel`) por clase +3. inspeccione contadores de clase y qdisc en conjunto +4. verifique que la dirección (`ingress`/`egress`) corresponda al problema +5. correlacione con latencia/throughput visibles al usuario, no solo con contadores + +## 9) Malentendidos Comunes + +1. "`fq_codel` o `CAKE` reemplaza HTB" + - Falso para la jerarquía de LibreQoS; HTB sigue siendo la envolvente de política. +2. "El tráfico no definido va a una cola HTB default en LibreQoS" + - Falso; LibreQoS deja pasar el tráfico no definido. +3. "Solo eventos de saturación dura se benefician de AQM" + - Falso. Los beneficios suelen verse cuando una cola gestionada tiene presión persistente (bursts, contención de flujos), incluso si la interfaz total está por debajo de 100%. + - Desde pruebas de mantenedor y feedback de despliegue: CAKE/HTB siguen siendo útiles en enlaces de baja tasa y asimétricos, donde el control de cola mejora usabilidad. + - Desde pruebas de mantenedor y feedback de despliegue: la dinámica de colas, no solo "enlace completamente pegado", determina el valor de AQM; en LibreQoS actual, el tráfico no definido es pass-through, por lo que esto se aplica a hojas HTB gestionadas. +4. "Ajustar qdisc hoja arregla jerarquía/mapeo roto" + - Falso; primero hay que corregir errores de mapeo/jerarquía. +5. "`fq_codel` puede limitar velocidad por sí solo" + - Falso; use HTB (u otro shaper) para política explícita de tasa. + +## 10) Contexto HTB HOWTO (Histórico, Aún Útil) + +Material clásico del HTB HOWTO sigue siendo útil como modelo mental, traducido al LibreQoS moderno: + +1. clasificar tráfico +2. programar servicio de colas +3. moldear en el cuello de botella (o justo aguas arriba) +4. definir intención explícita de clase con `rate`/`ceil` + +Notas de traducción moderna: + +1. confirme comportamiento con contadores `tc -s`, no con suposiciones de defaults +2. mantenga orden de clasificadores de forma intencional (reglas específicas antes de amplias) +3. incluya manejo catch-all explícito en despliegues manuales `tc` +4. en LibreQoS específicamente, tráfico no definido es pass-through salvo mapeo explícito a jerarquía moldeada + +## 11) Referencias + +- [Arquitectura Backend de LibreQoS](libreqos-backend-architecture-es.md) +- [CAKE (referencia rápida DSCP)](cake-es.md) +- [TreeGuard (Función Próxima de v2.0)](treeguard-es.md) +- [tc-htb man page (man7)](https://man7.org/linux/man-pages/man8/tc-htb.8.html) +- [tc-fq_codel man page (man7)](https://man7.org/linux/man-pages/man8/tc-fq_codel.8.html) +- [tc-cake man page (man7)](https://man7.org/linux/man-pages/man8/tc-cake.8.html) +- [FlowQueue-Codel RFC 8290](https://www.rfc-editor.org/rfc/rfc8290) +- [IANA DSCP Registry](https://www.iana.org/assignments/dscp-registry/dscp-registry.xhtml) +- [CAKE wiki (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/Cake/) +- [CAKE technical notes (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/CakeTechnical/) +- [FQ_Codel wiki (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/FQ_Codel/) +- [CAKE vs FQ_Codel (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/Cake_vs_FQ_CODEL/) +- [CoDel/fq_codel wiki index (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/) +- Toke Hoiland-Jorgensen, Dave Taht, Jonathan Morton. *Piece of CAKE: A Comprehensive Queue Management Solution for Home Gateways*, IEEE LANMAN, 2018. diff --git a/docs-es/v2.0/libreqos-backend-architecture-es.md b/docs-es/v2.0/libreqos-backend-architecture-es.md index 3816bbca..d9f36122 100644 --- a/docs-es/v2.0/libreqos-backend-architecture-es.md +++ b/docs-es/v2.0/libreqos-backend-architecture-es.md @@ -8,6 +8,8 @@ Esta página explica cómo se integran los sistemas backend de LibreQoS en tiemp 4. Actualizaciones del plano de control (Scheduler, `lqosd`, Bakery, incremental vs recarga completa) 5. Límites de diseño prácticos para operadores +Para un análisis profundo de colas, consulte [HTB + fq_codel + CAKE: Comportamiento Detallado de Colas](htb_fq_codel_cake-es.md). + ## Contexto de Fuente Esta página incorpora detalles de publicaciones públicas del devblog: @@ -350,6 +352,7 @@ Orden recomendado: ## Lectura Relacionada +- [HTB + fq_codel + CAKE: Comportamiento Detallado de Colas](htb_fq_codel_cake-es.md) - [CAKE](cake-es.md) - [Ajuste de Rendimiento](performance-tuning-es.md) - [Planificación de Escala y Diseño de Topología](scale-topology-es.md) diff --git a/docs-es/v2.0/treeguard-es.md b/docs-es/v2.0/treeguard-es.md new file mode 100644 index 00000000..ffb5eb51 --- /dev/null +++ b/docs-es/v2.0/treeguard-es.md @@ -0,0 +1,90 @@ +# TreeGuard (Función Próxima de v2.0) + +TreeGuard es una función próxima de LibreQoS v2.0 para gestión inteligente de nodos. + +Estado importante: + +1. TreeGuard es **próximo**. +2. TreeGuard **no está habilitado por defecto**. +3. Los valores por defecto actuales no cambian a menos que un operador habilite TreeGuard explícitamente. + +## Qué Hace TreeGuard + +TreeGuard tiene dos dominios de control: + +1. Gestión de virtualización de enlaces/nodos (para nodos seleccionados). +2. Conmutación de SQM por circuito entre `cake` y `fq_codel`. + +Para circuitos, TreeGuard puede tomar decisiones por dirección (descarga y subida de forma independiente). + +## Comportamiento por Defecto sin TreeGuard + +Cuando TreeGuard no está habilitado, LibreQoS mantiene la política SQM configurada/global (normalmente `cake diffserv4`, con overrides del operador cuando estén configurados). + +TreeGuard no afecta el tráfico si no está habilitado. + +## Modelo de Conmutación SQM por Circuito (Cuando Está Habilitado) + +TreeGuard evalúa utilización, frescura de RTT, guardrails de CPU y guardrails opcionales de QoO. + +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`. +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. + +## Configuración (`/etc/lqos.conf`) + +La configuración de TreeGuard vive bajo `[treeguard]` y sus sub-secciones: + +1. `[treeguard]`: habilitar/deshabilitar, dry-run, cadencia de ticks. +2. `[treeguard.cpu]`: modo basado en CPU vs tráfico/RTT y umbrales. +3. `[treeguard.links]`: enrolamiento de virtualización de nodos y guardrails. +4. `[treeguard.circuits]`: enrolamiento de circuitos y guardrails de conmutación SQM. +5. `[treeguard.qoo]`: umbral opcional de protección QoO. + +Valores por defecto iniciales (PR #946): + +```toml +[treeguard] +enabled = false +dry_run = true +tick_seconds = 1 + +[treeguard.circuits] +enabled = true +switching_enabled = true +independent_directions = true +idle_util_pct = 2.0 +idle_min_minutes = 15 +rtt_missing_seconds = 120 +upgrade_util_pct = 5.0 +min_switch_dwell_minutes = 30 +max_switches_per_hour = 4 +persist_sqm_overrides = true +``` + +## Patrón de Despliegue Seguro + +1. Mantenga `enabled = false` hasta revisar política y listas de enrolamiento. +2. Inicie con `enabled = true` y `dry_run = true`. +3. Use primero una allowlist pequeña de nodos/circuitos. +4. Valide el comportamiento en varias ventanas pico y valle. +5. Solo entonces establezca `dry_run = false`. + +## Overrides y Notas Operativas + +Cuando está habilitado y no está en dry-run, TreeGuard puede persistir decisiones 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. + +## Páginas Relacionadas + +- [HTB + fq_codel + CAKE: Comportamiento Detallado de Colas](htb_fq_codel_cake-es.md) +- [Referencia de Configuración Avanzada](configuration-advanced-es.md) +- [Arquitectura Backend de LibreQoS](libreqos-backend-architecture-es.md) +- [Insumos para Desarrollo Futuro](future-development-inputs-es.md) diff --git a/docs/v2.0/configuration-advanced.md b/docs/v2.0/configuration-advanced.md index b470363b..f7c2984e 100644 --- a/docs/v2.0/configuration-advanced.md +++ b/docs/v2.0/configuration-advanced.md @@ -238,6 +238,16 @@ Examples: If `sqm` is empty/missing, global queue defaults apply. +#### TreeGuard and per-circuit SQM (upcoming feature) + +TreeGuard is an upcoming v2.0 feature that can dynamically adjust per-circuit SQM (`cake`/`fq_codel`) based on circuit conditions. + +Important: +- TreeGuard is not enabled by default. +- Default LibreQoS behavior remains your configured/global SQM unless you explicitly enable TreeGuard. + +See [TreeGuard (Upcoming v2.0 Feature)](treeguard.md). + Here is an example of an entry in the ShapedDevices.csv file: | Circuit ID | Circuit Name | Device ID | Device Name | Parent Node | MAC | IPv4 | IPv6 | Download Min Mbps | Upload Min Mbps | Download Max Mbps | Upload Max Mbps | Comment | |------------|-----------------------------------------------------|-----------|-------------|-------------|-----|-------------------------|----------------------|-------------------|-----------------|-------------------|-----------------|---------| diff --git a/docs/v2.0/htb_fq_codel_cake.md b/docs/v2.0/htb_fq_codel_cake.md new file mode 100644 index 00000000..ce409b8a --- /dev/null +++ b/docs/v2.0/htb_fq_codel_cake.md @@ -0,0 +1,415 @@ +# HTB + fq_codel + CAKE: Detailed Queueing Behavior in LibreQoS + +This page is the canonical queueing deep-dive companion to [LibreQoS Backend Architecture](libreqos-backend-architecture.md). + +It explains: + +1. Why LibreQoS layers `HTB` with leaf qdiscs (`fq_codel` or `CAKE`) +2. How `fq_codel` works in practice +3. How `CAKE` works in practice +4. When to choose `fq_codel` vs `CAKE` +5. Operator troubleshooting and observability patterns + +## 1) Why These Three Components Exist Together + +In production LibreQoS: + +1. `HTB` provides hierarchical rate policy (`rate`, `ceil`, borrow, hierarchy) +2. `fq_codel` or `CAKE` provides per-flow queue service and AQM behavior inside each shaped envelope + +This split is intentional: + +- Policy problem: "How much can this class send?" -> `HTB` +- Queueing problem: "Which packet should send next while controlling latency?" -> `fq_codel`/`CAKE` + +## 2) Runtime Placement in LibreQoS + +Conceptually, packets pass through: + +1. `mq` root +2. `HTB` hierarchy +3. leaf qdisc per shaped class (`CAKE` by default, `fq_codel` optional) + +Operationally, this is commonly: + +`mq` root -> per-CPU HTB parents -> per-circuit HTB classes -> leaf qdisc (`cake diffserv4` or `fq_codel`) + +Each HTB class has a child qdisc attachment point. If no explicit leaf qdisc is attached, behavior falls back to kernel default queueing for that class. + +Practical LibreQoS behavior model: + +1. Default behavior uses `HTB` + `cake diffserv4` for shaped circuits. +2. TreeGuard (upcoming feature) can dynamically switch circuit directions between `cake diffserv4` and `fq_codel` based on low-load/RTT guardrails. +3. TreeGuard is not enabled by default. + +See [TreeGuard (Upcoming v2.0 Feature)](treeguard.md) for configuration and rollout details. + +## 3) HTB Summary for AQM Users + +### 3.1 Core HTB mechanics + +1. Tokens are consumed by packet bytes and refill over time. +2. `rate` defines guaranteed service. +3. `ceil` defines borrowable maximum when parent capacity exists. +4. Children borrow only from ancestor spare capacity. +5. Sibling contention is affected by `prio`, scheduler behavior, and class proportions. + +### 3.2 Key HTB controls + +- `rate`, `ceil` +- `prio` +- `burst`, `cburst` +- `quantum`, `r2q` +- `default` class minor ID (Linux HTB concept; see LibreQoS behavior note below) + +### 3.3 Why this matters for `fq_codel` and `CAKE` + +`fq_codel` and `CAKE` do not replace HTB's hierarchy and class-rate policy. They shape queue service inside the class envelope HTB allows. + +### 3.4 Undefined traffic behavior in LibreQoS + +LibreQoS behavior is explicit here: + +1. traffic not mapped to a shaped circuit is passed through +2. LibreQoS does not direct undefined traffic into HTB `default` classes +3. HTB `default` class behavior still exists in Linux `tc`, but it is not how LibreQoS handles undefined traffic + +Operationally, this means troubleshooting undefined traffic starts with classification/mapping validation, not with HTB default-class tuning. + +### 3.5 Compact HTB skeleton (reference pattern) + +Illustrative Linux HTB+leaf pattern: + +```bash +tc qdisc add dev root handle 1: htb default 30 +tc class add dev parent 1: classid 1:1 htb rate 1gbit ceil 1gbit +tc class add dev parent 1:1 classid 1:10 htb rate 700mbit ceil 1gbit prio 1 +tc class add dev parent 1:1 classid 1:20 htb rate 300mbit ceil 1gbit prio 2 +tc class add dev parent 1:1 classid 1:30 htb rate 10mbit ceil 1gbit prio 7 +tc qdisc add dev parent 1:10 cake diffserv4 +tc qdisc add dev parent 1:20 fq_codel +tc qdisc add dev parent 1:30 cake diffserv4 +tc filter add dev protocol ip parent 1:0 prio 1 u32 match ip src /32 flowid 1:10 +tc filter add dev protocol ip parent 1:0 prio 2 u32 match ip src /32 flowid 1:20 +``` + +In LibreQoS, queue/class commands are generated automatically and undefined traffic is passed through rather than sent to an HTB default class. + +## 4) fq_codel Deep Dive + +### 4.1 What fq_codel is + +`fq_codel` combines: + +1. stochastic flow queueing (hashed queues) +2. DRR-style fair scheduling across queues +3. CoDel AQM per queue + +Core references: + +- `tc-fq_codel(8)` +- RFC 8290 (Flow Queue CoDel) + +### 4.2 Scheduler behavior and sparse-flow benefit + +FQ-CoDel maintains "new" and "old" active queue lists. Newly active queues are prioritized over persistent backlogged queues, which naturally benefits sparse/interactive traffic. + +It also uses byte-credit (`quantum`) scheduling so fairness is byte-oriented, not packet-count oriented. + +### 4.3 Flow hashing model + +By default, packets are classified using a 5-tuple hash into a configurable number of buckets (`flows`). Hash collisions are possible and are a known tradeoff of stochastic queueing. + +### 4.4 fq_codel parameters that operators actually tune + +`tc-fq_codel(8)` parameters worth knowing: + +1. `limit PACKETS`: hard queue packet cap (default `10240`) +2. `memory_limit BYTES`: memory cap (default `32MB`), lower of limit and memory cap is enforced +3. `flows NUMBER`: hash buckets (default `1024`, set at creation time) +4. `target TIME`: acceptable minimum persistent delay (default `5ms`) +5. `interval TIME`: CoDel control window, generally order of worst RTT through bottleneck (default `100ms`) +6. `quantum BYTES`: DRR deficit quantum (default `1514`) +7. `ecn`/`noecn`: ECN on/off (`ecn` is default in fq_codel) +8. `ce_threshold TIME`: shallow ECN marking threshold for DCTCP-style use +9. `ce_threshold_selector VALUE/MASK`: apply CE threshold only to selected traffic +10. `drop_batch`: max drop batch when limits exceed (default `64`) + +### 4.5 fq_codel observability (`tc -s qdisc show`) + +Common counters/fields to inspect: + +1. `dropped`, `overlimits`, `requeues` +2. `drop_overlimit` +3. `new_flow_count` +4. `ecn_mark` +5. `new_flows_len`, `old_flows_len` +6. `backlog` + +Interpretation pattern: + +1. Verify queue pressure exists (`backlog`, `requeues`, `overlimits`) +2. Check whether AQM signaling is engaged (`ecn_mark`, `dropped`) +3. Correlate `new_flows_len`/`old_flows_len` with traffic mix (sparse vs bulk) + +## 5) CAKE Deep Dive + +### 5.1 CAKE architecture + +CAKE integrates multiple layers in one qdisc: + +1. deficit-mode shaper +2. priority queue (tins) +3. flow isolation (`DRR++`) +4. AQM (`COBALT`, combining CoDel + BLUE) +5. packet management and overhead compensation + +Core references: + +- `tc-cake(8)` +- Bufferbloat CAKE and CakeTechnical pages +- Piece of CAKE paper (`cake.pdf`) + +### 5.2 Shaped vs unshaped operation + +When `bandwidth` is set, CAKE's shaper and its derived tuning drive tin thresholds and timing behavior. + +Without shaping (`unlimited`), CAKE still provides queue service and AQM logic, but tin and service behavior are no longer operating against a fixed shaped bottleneck target. + +### 5.3 Flow isolation modes + +CAKE supports multiple fairness modes: + +1. `flowblind` (no flow isolation) +2. `flows` (5-tuple flow fairness) +3. `srchost`, `dsthost`, `hosts` +4. `dual-srchost`, `dual-dsthost` +5. `triple-isolate` (default in `tc-cake(8)`) + +Operational note: + +- `triple-isolate` is a safe general default when you need both per-flow and host fairness controls. + +### 5.4 NAT awareness + +`nat`/`nonat` controls whether CAKE performs NAT lookup before applying flow isolation. + +Why it matters: + +- Without `nat`, fairness sees post-NAT addresses only. +- With `nat`, fairness can better represent internal hosts behind NAT (when NAT is on the same box/path). + +### 5.5 DiffServ modes and tins + +Main priority presets: + +1. `besteffort` (single tin, no priority queue) +2. `diffserv3` +3. `diffserv4` +4. `diffserv8` +5. `precedence` (legacy, discouraged in modern deployments) + +`tc-cake(8)` currently documents `diffserv3` as default, while LibreQoS typically uses `cake diffserv4` as operator-facing default policy. + +### 5.6 LibreQoS `diffserv4` DSCP mapping + +LibreQoS commonly runs CAKE with `diffserv4`. Practical class mapping: + +1. Latency Sensitive: `CS7`, `CS6`, `EF`, `VA`, `CS5`, `CS4` +2. Streaming Media: `AF4x`, `AF3x`, `CS3`, `AF2x`, `TOS4`, `CS2`, `TOS1` +3. Best Effort: `CS0`, `AF1x`, `TOS2`, and unrecognized codepoints +4. Background Traffic: `CS1` + +Known codepoints in common operator use: + +1. `CS1` (Least Effort) +2. `CS0` (Best Effort) +3. `TOS1` (Max Reliability / LLT "Lo") +4. `TOS2` (Max Throughput) +5. `TOS4` (Min Delay) +6. `TOS5` (LLT "La") +7. `AF1x` +8. `AF2x` +9. `AF3x` +10. `AF4x` +11. `CS2` +12. `CS3` +13. `CS4` +14. `CS5` +15. `CS6` +16. `CS7` +17. `VA` +18. `EF` + +RFC 4594-style traffic-class framing (high-level): + +1. Network Control: `CS6`, `CS7` +2. Telephony: `EF`, `VA` +3. Signaling: `CS5` +4. Multimedia Conferencing: `AF4x` +5. Realtime Interactive: `CS4` +6. Multimedia Streaming: `AF3x` +7. Broadcast Video: `CS3` +8. Low Latency Data: `AF2x`, `TOS4` +9. Ops/Admin/Management: `CS2`, `TOS1` +10. Standard Service: `CS0` and unrecognized codepoints +11. High Throughput Data: `AF1x`, `TOS2` +12. Low Priority Data: `CS1` + +`fq_codel` note: + +1. `fq_codel` has no CAKE tin model and no CAKE-style DSCP class scheduler. +2. DSCP marking can still be used by external classification/policy, but not via CAKE `diffserv4` tin behavior. +3. In LibreQoS, DSCP priority behavior described above applies when CAKE with `diffserv4` is selected. + +### 5.7 Overhead and framing compensation + +CAKE can account for link-layer overhead/framing using: + +1. `overhead N` +2. `mpu N` +3. `atm`, `ptm`, `noatm` +4. shortcut keywords (`ethernet`, `docsis`, etc.) +5. `raw` and `conservative` + +Operator rule: + +- If overhead/framing is wrong, shaping accuracy is wrong. Validate with realistic traffic tests. + +### 5.8 GSO handling (`split-gso`) + +By default, CAKE splits GSO superpackets to reduce latency impact on competing flows, especially at lower rates. + +At very high link rates (e.g. >10 Gbps), `no-split-gso` can improve peak throughput, but may trade away latency smoothness. + +### 5.9 ACK filtering + +CAKE supports: + +1. `ack-filter` +2. `ack-filter-aggressive` +3. `no-ack-filter` (default) + +Best use case is asymmetric links where upstream ACK load limits downstream goodput. Apply conservatively and validate with application traffic, not only synthetic tests. + +### 5.10 Ingress mode and autorate + +`ingress` mode changes accounting and tuning for downlink shaping realities (including counting dropped packets as already-transited data). + +`autorate-ingress` can estimate capacity from arriving traffic and is primarily useful on highly variable links (for example some cellular paths). It cannot estimate bottlenecks downstream of where CAKE is attached. + +### 5.11 CAKE observability (`tc -s qdisc show`) + +Useful fields commonly present: + +1. top-level: `dropped`, `overlimits`, `backlog`, `memory used`, `capacity estimate` +2. per tin: `thresh`, `target`, `interval` +3. delay telemetry: `pk_delay`, `av_delay`, `sp_delay` +4. hashing: `way_inds`, `way_miss`, `way_cols` +5. signaling: `drops`, `marks` +6. ACK filtering: `ack_drop` +7. queue activity: `sp_flows`, `bk_flows`, `un_flows`, `max_len`, `quantum` + +Interpretation pattern: + +1. check if tins and thresholds match intended policy +2. inspect delay EWMAs by tin +3. correlate `drops`/`marks` with user-visible latency and throughput +4. monitor hash-collision indicators (`way_cols`) under peak concurrency + +## 6) LibreQoS Policy Framing: CAKE vs fq_codel + +For LibreQoS operators, start with platform behavior first: + +1. Default operation is `cake diffserv4` in HTB class leaves. +2. TreeGuard (upcoming feature) can move selected circuit directions to `fq_codel` during sustained low-load conditions and back to `cake` as utilization/guardrail pressure rises. +3. Manual per-circuit `sqm` overrides still provide explicit operator control. + +Use this matrix for tradeoff context: + +| Dimension | `fq_codel` | `CAKE` | +|---|---|---| +| Configuration complexity | Lower | Higher (more integrated features) | +| Resource footprint at scale | Often lower | Often higher | +| Integrated shaping features | No (needs parent shaper like HTB) | Yes (deficit-mode shaper built in) | +| DiffServ/tin behavior | Basic/indirect | Strong native tin model | +| Host isolation modes | Not CAKE-style host modes | Rich host/flow isolation modes | +| Overhead compensation | Limited | Rich built-in overhead/framing controls | +| Asymmetric-link ACK optimizations | None | ACK filtering modes available | +| Best fit | Large queue count with tight resources | Mixed traffic where policy richness and smoothness matter | + +## 7) LibreQoS Operator Notes + +From maintainer testing and deployment feedback: + +1. `fq_codel` has no intrinsic rate limiting; it relies on HTB for rate policy. +2. `fq_codel` and `CAKE` both keep per-flow state tables, so RAM/hash behavior matters at high queue counts. +3. `CAKE` and HTB are viable down to very low and asymmetric rates in LibreQoS deployments. +4. A top-level "sandwich" limiter pattern using HTB+fq_codel is a practical deployment option in some environments. +5. Some dashboard traffic views can reflect pre-drop context; interpret counters with drop/mark semantics together. +6. "Only hard saturation benefits from AQM" is too narrow; AQM and fair queueing can improve latency when managed queues are under burst/contended pressure, even before interface-wide utilization is fully pegged. +7. Older shared/default-bucket discussion patterns reinforce that queue dynamics, not only "link fully pegged" moments, drive AQM value; in current LibreQoS, undefined traffic is pass-through, so apply this principle to managed HTB leaf queues. + +## 8) Practical Observability Workflow + +Start with: + +```bash +tc -s qdisc show dev +tc -s class show dev +``` + +Then: + +1. confirm HTB classes exist where expected +2. confirm leaf qdisc type (`cake` vs `fq_codel`) per class +3. inspect class and qdisc counters together +4. verify directionality (`ingress`/`egress`) matches the problem being diagnosed +5. correlate with user-visible latency/throughput, not counters alone + +## 9) Common Misunderstandings + +1. "`fq_codel` or `CAKE` replaces HTB" + - False for LibreQoS hierarchy operation; HTB remains the policy envelope. +2. "Undefined traffic goes to an HTB default queue in LibreQoS" + - False; LibreQoS passes undefined traffic through. +3. "Only hard saturation events benefit from AQM" + - False. Benefits are often visible whenever a managed queue has persistent pressure (bursts, mixed-flow contention), even if total interface utilization is below 100%. + - From maintainer testing and deployment feedback: CAKE/HTB remain useful on very low and asymmetric links, where queue control still improves usability. + - From maintainer testing and deployment feedback: queue dynamics, not just "link fully pegged," drive AQM value; in current LibreQoS, undefined traffic is pass-through, so apply this principle to managed HTB leaves. +4. "Leaf qdisc tuning can fix broken hierarchy/class mapping" + - False; mapping/hierarchy errors must be corrected first. +5. "`fq_codel` can rate-limit on its own" + - False; use HTB (or another shaper) for explicit rate policy. + +## 10) HTB HOWTO Context (Historical, Still Useful) + +Classic HTB HOWTO material remains useful for operator mental models when translated to modern LibreQoS: + +1. classify traffic +2. schedule queue service +3. shape at the bottleneck (or immediately upstream) +4. define explicit class intent with `rate`/`ceil` + +Modern translation notes: + +1. confirm behavior with `tc -s` counters, not assumptions about package defaults +2. keep classifier order intentional (specific rules before broader matches) +3. include explicit catch-all handling in manual `tc` deployments +4. in LibreQoS specifically, undefined traffic is pass-through unless mapped into shaped hierarchy + +## 11) References + +- [LibreQoS Backend Architecture](libreqos-backend-architecture.md) +- [CAKE (DSCP quick reference)](cake.md) +- [tc-htb man page (man7)](https://man7.org/linux/man-pages/man8/tc-htb.8.html) +- [tc-fq_codel man page (man7)](https://man7.org/linux/man-pages/man8/tc-fq_codel.8.html) +- [tc-cake man page (man7)](https://man7.org/linux/man-pages/man8/tc-cake.8.html) +- [FlowQueue-Codel RFC 8290](https://www.rfc-editor.org/rfc/rfc8290) +- [IANA DSCP Registry](https://www.iana.org/assignments/dscp-registry/dscp-registry.xhtml) +- [CAKE wiki (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/Cake/) +- [CAKE technical notes (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/CakeTechnical/) +- [FQ_Codel wiki (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/FQ_Codel/) +- [CAKE vs FQ_Codel (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/Cake_vs_FQ_CODEL/) +- [CoDel/fq_codel project wiki index (Bufferbloat)](https://www.bufferbloat.net/projects/codel/wiki/) +- Toke Høiland-Jorgensen, Dave Taht, Jonathan Morton. *Piece of CAKE: A Comprehensive Queue Management Solution for Home Gateways*, IEEE LANMAN, 2018. diff --git a/docs/v2.0/libreqos-backend-architecture.md b/docs/v2.0/libreqos-backend-architecture.md index ab720bec..9bcff4dc 100644 --- a/docs/v2.0/libreqos-backend-architecture.md +++ b/docs/v2.0/libreqos-backend-architecture.md @@ -7,6 +7,8 @@ This page explains how LibreQoS backend systems fit together at runtime: 3. AQM behavior (`fq_codel`, `CAKE`) and why benefits can appear below strict line rate 4. Control-path updates (Scheduler, `lqosd`, Bakery, incremental vs full reload) 5. Practical design boundaries for operators + +For a full queueing deep-dive, see [HTB + fq_codel + CAKE: Detailed Queueing Behavior](htb_fq_codel_cake.md). ## Source Context @@ -358,10 +360,11 @@ Recommended order: ## Related Reading -- [CAKE](cake.md) +- [HTB + fq_codel + CAKE: Detailed Queueing Behavior](htb_fq_codel_cake.md) +- [CAKE (DSCP quick reference)](cake.md) - [Performance Tuning](performance-tuning.md) - [Scale Planning and Topology Design](scale-topology.md) - [Best Practices Guide for ISP Operations](best-practices.md) - [Deployment Recipes](recipes.md) -- [Introducing the LibreQoS Bakery (Herbert)](https://devblog.libreqos.com/posts/0005-lqos-bakery/) -- [Fixing the Reload Penalty in LibreQoS (Herbert)](https://devblog.libreqos.com/posts/0013-no-more-locks/) +- [Introducing the LibreQoS Bakery](https://devblog.libreqos.com/posts/0005-lqos-bakery/) +- [Fixing the Reload Penalty in LibreQoS](https://devblog.libreqos.com/posts/0013-no-more-locks/) diff --git a/docs/v2.0/treeguard.md b/docs/v2.0/treeguard.md new file mode 100644 index 00000000..c1def523 --- /dev/null +++ b/docs/v2.0/treeguard.md @@ -0,0 +1,90 @@ +# TreeGuard (Upcoming v2.0 Feature) + +TreeGuard is an upcoming LibreQoS v2.0 feature for intelligent node management. + +Important status: + +1. TreeGuard is **upcoming**. +2. TreeGuard is **not enabled by default**. +3. Current defaults remain unchanged unless an operator explicitly enables TreeGuard. + +## What TreeGuard Does + +TreeGuard has two control domains: + +1. Link/node virtualization management (for selected nodes). +2. Per-circuit SQM switching between `cake` and `fq_codel`. + +For circuits, TreeGuard can make per-direction decisions (download and upload independently). + +## Default Behavior Without TreeGuard + +When TreeGuard is not enabled, LibreQoS behavior stays with configured/default SQM policy (commonly `cake diffserv4`, with operator overrides where configured). + +TreeGuard does not affect traffic unless enabled. + +## Circuit SQM Switching Model (When Enabled) + +TreeGuard evaluates utilization, RTT freshness, CPU guardrails, and optional QoO guardrails. + +High-level behavior: + +1. For sustained low-load conditions, TreeGuard may switch a direction from `cake` to `fq_codel`. +2. If utilization rises, RTT/QoO guardrails are unsafe, or revert conditions are met, TreeGuard switches back to `cake`. +3. Decisions can be independent per direction when `independent_directions = true`. + +This gives a dynamic profile where loaded directions favor `cake diffserv4`, while low-load directions can use `fq_codel` when conditions are safe. + +## Configuration (`/etc/lqos.conf`) + +TreeGuard config lives under `[treeguard]` and sub-sections: + +1. `[treeguard]`: enable/disable, dry-run, tick cadence. +2. `[treeguard.cpu]`: CPU-aware vs traffic/RTT mode and thresholds. +3. `[treeguard.links]`: node virtualization enrollment and guardrails. +4. `[treeguard.circuits]`: circuit enrollment and SQM switching guardrails. +5. `[treeguard.qoo]`: optional QoO protection threshold. + +From PR #946 defaults: + +```toml +[treeguard] +enabled = false +dry_run = true +tick_seconds = 1 + +[treeguard.circuits] +enabled = true +switching_enabled = true +independent_directions = true +idle_util_pct = 2.0 +idle_min_minutes = 15 +rtt_missing_seconds = 120 +upgrade_util_pct = 5.0 +min_switch_dwell_minutes = 30 +max_switches_per_hour = 4 +persist_sqm_overrides = true +``` + +## Safe Rollout Pattern + +1. Keep `enabled = false` until you have reviewed policy and enrollment lists. +2. Start with `enabled = true` and `dry_run = true`. +3. Use a small allowlist of nodes/circuits first. +4. Validate behavior over multiple peak/off-peak windows. +5. Only then set `dry_run = false`. + +## Overrides and Operational Notes + +When enabled and not dry-run, TreeGuard may persist decisions to: + +- `lqos_overrides.treeguard.json` + +TreeGuard is designed to avoid fighting operator-owned overrides. If operator overrides exist for enrolled entities, TreeGuard skips those entities and reports warnings. + +## Related Pages + +- [HTB + fq_codel + CAKE: Detailed Queueing Behavior](htb_fq_codel_cake.md) +- [Advanced Configuration Reference](configuration-advanced.md) +- [LibreQoS Backend Architecture](libreqos-backend-architecture.md) +- [Future Development Inputs](future-development-inputs.md) diff --git a/index.rst b/index.rst index 7892468d..a222964d 100644 --- a/index.rst +++ b/index.rst @@ -31,6 +31,7 @@ Welcome to the LibreQoS documentation docs/v2.0/node-manager-ui docs/v2.0/scale-topology docs/v2.0/stormguard + docs/v2.0/treeguard docs/v2.0/high-availability docs/v2.0/recipes docs/v2.0/case-studies