From b8a595f9f026371245facc577292d18b63146e84 Mon Sep 17 00:00:00 2001 From: Robert Chacon Date: Thu, 26 Feb 2026 09:05:37 -0700 Subject: [PATCH] changes --- docs-es/v2.0/quickstart-es.md | 171 +++++++++++++++------------------- docs/v2.0/quickstart.md | 171 ++++++++++++++-------------------- 2 files changed, 145 insertions(+), 197 deletions(-) diff --git a/docs-es/v2.0/quickstart-es.md b/docs-es/v2.0/quickstart-es.md index c8d4ca89..dc141ae8 100644 --- a/docs-es/v2.0/quickstart-es.md +++ b/docs-es/v2.0/quickstart-es.md @@ -1,21 +1,24 @@ -# Quickstart: Elija su ruta de despliegue +# Quickstart: Ruta de Despliegue para ISP -Use esta página para elegir rápidamente la ruta correcta y ejecutar solo los pasos de esa ruta. +Use esta página para pasar de instalación a piloto seguro con mínima ambigüedad. ¿Necesita definiciones de términos clave? Vea el [Glosario](glossary-es.md). -## Base de instalación común +## 1) Base de instalación común -Complete esto una vez antes de cualquier paso específico de ruta. +Complete esto una vez: + +1. Revise arquitectura y dimensionamiento: +- [Escenarios de Despliegue](design-es.md) +- [Requisitos del Sistema](requirements-es.md) -1. Revise supuestos de despliegue y capacidad: - - [Escenarios de Despliegue](design-es.md) - - [Requisitos del Sistema](requirements-es.md) 2. Prepare host y sistema operativo: - - [Configuración del Servidor - Prerrequisitos](prereq-es.md) - - [Instalar Ubuntu Server 24.04](ubuntu-server-es.md) +- [Configuración del Servidor - Prerrequisitos](prereq-es.md) +- [Instalar Ubuntu Server 24.04](ubuntu-server-es.md) + 3. Configure el modo de puente: - - [Configurar Puente de Regulación](bridge-es.md) +- [Configurar Puente de Regulación](bridge-es.md) + 4. Instale LibreQoS (`.deb` recomendado): ```bash @@ -28,127 +31,107 @@ sudo apt install ./{deb_url_v1_5} 5. Abra WebUI en `http://your_shaper_ip:9123`. -## Después de instalar: estado esperado (10 minutos) +## 2) Puerta de salud en 10 minutos (obligatoria antes del piloto) -Antes de cambios profundos, valide base operativa: +Ejecute: -1. Servicios activos: ```bash sudo systemctl status lqosd lqos_scheduler -``` -2. WebUI carga y actualiza (Dashboard + Scheduler Status). -3. Sin errores críticos recientes: -```bash journalctl -u lqosd -u lqos_scheduler --since "10 minutes ago" ``` -4. Fuente de verdad definida: -- modo integración: la integración controla refresco de archivos -- modo custom/manual: sus archivos/scripts controlan persistencia -Si falla algo, pase a [Solución de problemas](troubleshooting-es.md) antes del piloto. +Confirme: +- Carga WebUI Dashboard. +- Scheduler Status está saludable. +- No hay errores urgentes/fatales de arranque en logs. -## Decidir fuente de verdad (hágalo una vez) +Si falla esto, vaya a [Solución de problemas](troubleshooting-es.md) antes de continuar. -Antes de continuar, elija quién controla las actualizaciones persistentes de datos de shaping: +## 3) Decisión A: Etapa de despliegue -| Si esto describe su caso | Elija este modo | Siguiente página | +Elija una: + +- **Laboratorio primero**: validar comportamiento en entorno controlado antes de tráfico inline. +- **Piloto inline ahora**: avanzar directo con alcance limitado de tráfico productivo. + +Si elige laboratorio primero: +1. Arme topología de laboratorio. +2. Genere tráfico de prueba. +3. Valide Dashboard, Tree, Flow, Scheduler Status y Urgent Issues. +4. Continúe a la Decisión B. + +## 4) Decisión B: Fuente de verdad (elija un dueño) + +| Si esto describe su caso | Modo | Dueño de datos de shaping durables | |---|---|---| -| Usa una integración CRM/NMS soportada | Modo integración incluida | [Integraciones CRM/NMS](integrations-es.md) | -| Genera `network.json` y `ShapedDevices.csv` con scripts propios | Modo fuente de verdad personalizada | [Modos de operación y fuente de verdad](operating-modes-es.md) | -| Mantiene archivos manualmente (redes pequeñas/simples) | Modo archivos manuales | [Modos de operación y fuente de verdad](operating-modes-es.md) | +| Usa integración CRM/NMS soportada | Modo integración incluida | Jobs de integración | +| Genera `network.json` y `ShapedDevices.csv` con scripts propios | Modo fuente de verdad personalizada | Sus scripts | +| Mantiene archivos manualmente en red pequeña/simple | Modo archivos manuales | Edición manual | -Regla: mantenga un único dueño para los insumos persistentes de shaping para evitar conflictos de sobrescritura. +Regla: mantenga un único dueño para insumos persistentes de shaping. -## Testbed / Lab +## 5) Tarjetas de ruta -### Cuándo elegir +### Modo Integración Incluida -Quiere validar comportamiento en un entorno controlado antes de producción inline. +Cuándo elegir: +- Su CRM/NMS está soportado por integraciones incluidas. -### Haga esto ahora - -1. Arme topología de laboratorio (LibreQoS + endpoints generadores de tráfico + simulación opcional OSPF/BGP). -2. Elija una pista de laboratorio: - - **Lab con archivos manuales**: validar comportamiento de `network.json` + `ShapedDevices.csv`. - - **Lab con integración soportada**: validar datos importados de suscriptores/topología. -3. Genere tráfico y valide en WebUI (Dashboard, Tree, Flow, Scheduler Status, Urgent Issues). -4. Confirme comportamiento de shaping y estabilidad esperada. - -### Luego vaya aquí - -- [Configurar LibreQoS](configuration-es.md) -- [Solución de problemas](troubleshooting-es.md) - -## Integración Soportada - -### Cuándo elegir - -Su CRM/NMS está soportado por integraciones incluidas de LibreQoS. - -### Haga esto ahora - -1. Configure la integración en WebUI. -2. Ejecute sincronización inicial y valide datos importados. +Haga esto ahora: +1. Configure integración en WebUI. +2. Ejecute sincronización inicial y valide datos importados de shaping/topología. 3. Coloque LibreQoS inline para tráfico piloto. -4. Valide señales de salud en WebUI (Scheduler Status, Urgent Issues, vistas de topología/flujo). -5. Expanda alcance del piloto tras operación estable. - -Nota: -- En modo integración, `ShapedDevices.csv` normalmente se regenera por los jobs de sincronización. -- La sobrescritura de `network.json` depende de configuración (por ejemplo `always_overwrite_network_json`). - -### Luego vaya aquí +4. Valide Scheduler Status, Urgent Issues y vistas de topología/flujo. +5. Expanda alcance del piloto tras estabilidad. +Siguiente: - [Integraciones CRM/NMS](integrations-es.md) - [Solución de problemas](troubleshooting-es.md) -## Errores comunes en primera puesta en marcha +### Modo Fuente de Verdad Personalizada (Sus Scripts) -- Fuente de verdad no definida entre integración y edición manual. -- Elegir estrategia topológica profunda sin validar salud base. -- Omitir checks de servicios/logs antes de tráfico piloto. - -## Integración con Script Personalizado - -### Cuándo elegir - -Su CRM/NMS no está soportado y usted generará `network.json` + `ShapedDevices.csv` con su propio pipeline. - -### Haga esto ahora +Cuándo elegir: +- Su CRM/NMS no está soportado y usted generará `network.json` + `ShapedDevices.csv` con su pipeline propio. +Haga esto ahora: 1. Implemente script/proceso para generar y refrescar archivos de shaping. -2. Declare salidas del script como fuente de verdad. +2. Declare salidas del script como su fuente de verdad. 3. Coloque LibreQoS inline para tráfico piloto. -4. Use WebUI para verificaciones operativas y ajustes rápidos. -5. Lleve cambios permanentes de vuelta al flujo de scripts. +4. Use WebUI para checks operativos y ajustes de corto plazo. +5. Mantenga cambios permanentes en su flujo externo de scripts. -Nota: -- Las ediciones por WebUI son útiles para operación rápida. -- El estado de largo plazo debe mantenerse en su flujo externo de fuente de verdad. -- Referencia de formato de archivos: vea las secciones `network.json` y `ShapedDevices.csv` en la [Referencia avanzada de configuración](configuration-advanced-es.md). - -### Luego vaya aquí +Referencia de formato: +- Vea las secciones `network.json` y `ShapedDevices.csv` en [Referencia avanzada de configuración](configuration-advanced-es.md). +Siguiente: - [Modos de operación y fuente de verdad](operating-modes-es.md) - [Solución de problemas](troubleshooting-es.md) -## Archivos Manuales (<100 suscriptores) +### Modo Archivos Manuales (<100 suscriptores) -### Cuándo elegir - -Mantiene intencionalmente `network.json` + `ShapedDevices.csv` sin sincronización CRM/NMS. - -Recomendado solo para redes menores a 100 suscriptores. - -### Haga esto ahora +Cuándo elegir: +- Mantiene intencionalmente `network.json` + `ShapedDevices.csv` sin sincronización CRM/NMS. +Haga esto ahora: 1. Construya y mantenga archivos de shaping directamente. 2. Coloque LibreQoS inline para tráfico piloto. 3. Valide shaping y estado del scheduler en WebUI. 4. Mantenga disciplina estricta de cambios manuales. 5. Planifique migración a integración soportada o scripts si crece escala/volumen de cambios. -### Luego vaya aquí - +Siguiente: +- [Referencia avanzada de configuración](configuration-advanced-es.md) +- [Solución de problemas](troubleshooting-es.md) + +## 6) Errores comunes en primera puesta en marcha + +- Propiedad poco clara de la fuente de verdad entre integración y edición manual. +- Cambiar profundidad topológica antes de pasar la puerta de salud. +- Omitir validación de servicios/logs antes de tráfico piloto. + +## 7) Páginas relacionadas + +- [Modos de operación y fuente de verdad](operating-modes-es.md) +- [Integraciones CRM/NMS](integrations-es.md) - [Referencia avanzada de configuración](configuration-advanced-es.md) - [Solución de problemas](troubleshooting-es.md) diff --git a/docs/v2.0/quickstart.md b/docs/v2.0/quickstart.md index 2fd7ba68..1190e0c1 100644 --- a/docs/v2.0/quickstart.md +++ b/docs/v2.0/quickstart.md @@ -1,35 +1,24 @@ -# Quickstart: Choose Your Deployment Path +# Quickstart: ISP Deployment Path -Use this page to choose the correct deployment path quickly, then execute only the steps for that path. +Use this page to move from install to a safe pilot with minimal ambiguity. Need definitions for key terms? See the [Glossary](glossary.md). -```{mermaid} -flowchart TD - A[Start Here: Quickstart] --> B{Choose Path} - B --> C[Testbed / Lab] - B --> D[Supported Integration] - B --> E[Custom Script Integration] - B --> F[Manual Files <100 subscribers] - C --> G[Configure + Validate in WebUI] - D --> G - E --> G - F --> G - G --> H[Troubleshoot / Optimize / Scale] -``` +## 1) Common Install Foundation -## Common Install Foundation +Complete this once: -Complete this once before any path-specific steps. +1. Review architecture and sizing: +- [Deployment Scenarios](design.md) +- [System Requirements](requirements.md) -1. Review deployment assumptions and capacity: - - [Deployment Scenarios](design.md) - - [System Requirements](requirements.md) 2. Prepare host and OS: - - [Server Setup - Prerequisites](prereq.md) - - [Install Ubuntu Server 24.04](ubuntu-server.md) +- [Server Setup - Prerequisites](prereq.md) +- [Install Ubuntu Server 24.04](ubuntu-server.md) + 3. Configure bridge mode: - - [Configure Shaping Bridge](bridge.md) +- [Configure Shaping Bridge](bridge.md) + 4. Install LibreQoS (`.deb` recommended): ```bash @@ -42,131 +31,107 @@ sudo apt install ./{deb_url_v1_5} 5. Open WebUI at `http://your_shaper_ip:9123`. -## After Install: What Good Looks Like (10-Minute Check) +## 2) 10-Minute Health Gate (Required Before Pilot) -Before deeper configuration, verify baseline health: +Run: -1. Services are active: ```bash sudo systemctl status lqosd lqos_scheduler -``` -2. WebUI loads and updates (Dashboard + Scheduler Status). -3. No urgent/fatal errors in recent logs: -```bash journalctl -u lqosd -u lqos_scheduler --since "10 minutes ago" ``` -4. Your chosen source of truth is clear: -- integration mode: integration owns refresh of shaping inputs -- custom/manual mode: your files/scripts own persistence -If these checks fail, continue in [Troubleshooting](troubleshooting.md) before pilot rollout. +Confirm: +- WebUI Dashboard loads. +- Scheduler Status is healthy. +- No urgent/fatal startup errors in logs. -## Decide Source of Truth (Do This Once) +If this fails, go to [Troubleshooting](troubleshooting.md) before proceeding. -Before continuing, choose who owns ongoing shaping data updates: +## 3) Decision A: Deployment Stage -| If this describes you | Choose this mode | Next page | +Choose one: + +- **Lab first**: validate behavior in a controlled environment before inline traffic. +- **Inline pilot now**: proceed directly with limited production traffic. + +If lab-first: +1. Build a lab topology. +2. Generate test traffic. +3. Validate Dashboard, Tree, Flow, Scheduler Status, and Urgent Issues. +4. Continue to Decision B. + +## 4) Decision B: Source of Truth (Pick One Owner) + +| If this describes you | Mode | Owner of durable shaping data | |---|---|---| -| You use a supported CRM/NMS integration | Built-in integration mode | [CRM/NMS Integrations](integrations.md) | -| You generate `network.json` and `ShapedDevices.csv` from your own scripts | Custom source of truth mode | [Operating Modes and Source of Truth](operating-modes.md) | -| You maintain files directly (small/simple networks) | Manual files mode | [Operating Modes and Source of Truth](operating-modes.md) | +| You use a supported CRM/NMS integration | Built-in integration mode | Integration jobs | +| You generate `network.json` and `ShapedDevices.csv` with your own scripts | Custom source of truth mode | Your scripts | +| You maintain files manually for a small/simple network | Manual files mode | Manual edits | -Rule: keep one owner for persistent shaping inputs to avoid overwrite conflicts. +Rule: keep one owner for persistent shaping inputs. -## Testbed / Lab +## 5) Path Cards -### When to choose +### Built-In Integration Mode -You want to validate behavior in a controlled environment before inline production. - -### Do this now - -1. Build a lab topology (LibreQoS + traffic generator endpoints + optional OSPF/BGP path simulation). -2. Choose a lab track: - - **Lab with manual files**: validate `network.json` + `ShapedDevices.csv` behavior. - - **Lab with supported integration**: validate imported subscriber/topology data. -3. Generate traffic and validate in WebUI (Dashboard, Tree, Flow, Scheduler Status, Urgent Issues). -4. Confirm expected shaping behavior and stability. - -### Then go here - -- [Configure LibreQoS](configuration.md) -- [Troubleshooting](troubleshooting.md) - -## Supported Integration - -### When to choose - -Your CRM/NMS is supported by built-in LibreQoS integrations. - -### Do this now +When to choose: +- Your CRM/NMS is supported by built-in integrations. +Do this now: 1. Configure integration settings in WebUI. 2. Run initial sync and validate imported shaping/topology data. 3. Place LibreQoS inline for pilot traffic. -4. Validate WebUI health signals (Scheduler Status, Urgent Issues, topology/flow views). +4. Validate Scheduler Status, Urgent Issues, and topology/flow views. 5. Expand pilot scope after stable operation. -Note: -- In integration mode, `ShapedDevices.csv` is typically regenerated by sync jobs. -- `network.json` overwrite behavior depends on integration settings (for example `always_overwrite_network_json`). - -### Then go here - +Next: - [CRM/NMS Integrations](integrations.md) - [Troubleshooting](troubleshooting.md) -## Custom Script Integration +### Custom Source of Truth (Your Scripts) -### When to choose - -Your CRM/NMS is unsupported and you will generate `network.json` + `ShapedDevices.csv` with your own pipeline. - -### Do this now +When to choose: +- Your CRM/NMS is unsupported and you generate `network.json` + `ShapedDevices.csv` with your own pipeline. +Do this now: 1. Implement script/process to generate and refresh shaping files. -2. Declare your script outputs as source of truth. +2. Declare script outputs as your source of truth. 3. Place LibreQoS inline for pilot traffic. -4. Use WebUI for operational checks and quick adjustments. -5. Move permanent changes back into your script workflow. +4. Use WebUI for operational checks and short-term adjustments. +5. Keep permanent changes in your external script workflow. -Note: -- WebUI edits are useful for quick operations. -- Long-term state should be maintained by your external source of truth workflow. -- File format reference: see `network.json` and `ShapedDevices.csv` sections in [Advanced Configuration Reference](configuration-advanced.md). - -### Then go here +Format reference: +- See `network.json` and `ShapedDevices.csv` sections in [Advanced Configuration Reference](configuration-advanced.md). +Next: - [Operating Modes and Source of Truth](operating-modes.md) - [Troubleshooting](troubleshooting.md) -## Manual Files (<100 subscribers) +### Manual Files Mode (<100 Subscribers) -### When to choose - -You intentionally maintain `network.json` + `ShapedDevices.csv` directly without CRM/NMS synchronization. - -Recommended only for networks under 100 subscribers. - -### Do this now +When to choose: +- You intentionally maintain `network.json` + `ShapedDevices.csv` without CRM/NMS synchronization. +Do this now: 1. Build and maintain shaping files directly. 2. Place LibreQoS inline for pilot traffic. 3. Validate shaping and scheduler status in WebUI. 4. Maintain strict manual change discipline. -5. Plan migration to supported integration or custom scripts if scale/change volume grows. - -### Then go here +5. Plan migration to supported integration or scripts if scale/change volume grows. +Next: - [Advanced Configuration Reference](configuration-advanced.md) - [Troubleshooting](troubleshooting.md) -## Common First-Run Mistakes +## 6) Common First-Run Mistakes - Unclear source of truth ownership between integration and manual edits. -- Choosing deeper topology strategy before confirming baseline health. -- Skipping post-install service/log checks before pilot traffic. +- Changing topology depth before passing the health gate. +- Skipping post-change service/log validation before pilot traffic. + +## 7) Related Pages -Use: - [Operating Modes and Source of Truth](operating-modes.md) +- [CRM/NMS Integrations](integrations.md) +- [Advanced Configuration Reference](configuration-advanced.md) - [Troubleshooting](troubleshooting.md)