Saltar a contenido

Elina Traffic Controller (Elina-TC)

Introducción

Elina-TC es una potente herramienta de línea de comandos para la degradación y la emulación de redes en Linux. Proporciona una interfaz sencilla para los subsistemas Traffic Control (tc) y NetEm (netem) integrados en el kernel de Linux, lo que le permite simular una gran variedad de condiciones de red realistas en una interfaz de red determinada.

Elina-TC destaca como herramienta independiente para pruebas de red, análisis de resiliencia de aplicaciones y validación del rendimiento. También está diseñada para integrarse con un generador de tráfico, como Elina-TG, lo que le permite generar tráfico de aplicación mientras degrada simultáneamente la ruta de red. Esto le permite medir y comprender el impacto directo de las degradaciones de red en el rendimiento de la aplicación.

Cómo funciona

Elina-TC aplica reglas de degradación de red al tráfico ingress (descarga) y egress (subida) de una interfaz de red especificada, lo que le permite probar el impacto de las condiciones de red en su aplicación. Utiliza un dispositivo virtual Intermediate Functional Block (ifb) para realizar estas modificaciones.

Importante — modelado simétrico: Las degradaciones se aplican en ambas direcciones. Un perfil con delay: "50ms" añade unos 50 ms en subida y 50 ms en bajada (~100 ms de RTT). Un límite rate: "10mbit" se aplica a ambas direcciones. Esto es especialmente importante con los perfiles /asymmetric: para probar una dirección concreta (p. ej. 400 Mbps en bajada), aplique un perfil cuyo caudal simétrico corresponda a ese cuello de botella y, después, cambie de perfil para probar la otra dirección.

La herramienta puede ejecutarse en varios modos:

  • On-the-Fly: Para aplicar rápidamente degradaciones temporales directamente desde la línea de comandos.
  • Batch: Para ejecutar secuencias de prueba automatizadas recorriendo perfiles de degradación predefinidos.
  • Interactive: Para el control en tiempo real de las condiciones de red, ideal para la depuración y las pruebas exploratorias.
  • Validate: Para verificar la sintaxis y la exactitud lógica de los archivos de perfil antes de su uso.

Capacidades

  • Limitación del caudal (TBF), retardo, jitter, pérdida de paquetes, duplicación, corrupción, reordenación y límites de cola (netem)
  • Modelado simétrico ingress/egress mediante un dispositivo IFB
  • Modo dry-run para previsualizar los comandos tc sin aplicarlos
  • Estadísticas tc -s opcionales en los modos Batch (--show-stats) e Interactive (stats, watch stats)
  • Validación de los perfiles con nombre de archivo, índice de perfil y descripción en los informes de error

Configuración

Elina-TC es una aplicación Python y requiere Python 3.7+ en un sistema operativo Linux.

1. Requisitos previos: Asegúrese de tener instalados los paquetes del sistema necesarios. En Debian/Ubuntu, puede hacerlo con:

sudo apt-get update && sudo apt-get install -y python3-pip python3-venv iproute2

2. Descargar y descomprimir la herramienta:

wget https://api.latence.ca/software/elina-tc.zip
unzip elina-tc.zip
cd elina-tc-release

3. Configurar un entorno virtual (Recomendado): Se recomienda encarecidamente para aislar las dependencias de Elina-TC.

python3 -m venv venv
source venv/bin/activate

4. Instalar Elina-TC: * Para la herramienta de línea de comandos principal y la interfaz web (beta):

pip install .[ui]

Esto hará que el comando elina-tc esté disponible e instalará las bibliotecas necesarias para el servidor web.

5. Configuración de sudoers (CRÍTICO):

La interfaz de usuario y algunas funcionalidades de la CLI ejecutan elina-tc utilizando sudo. Para un funcionamiento sin contraseña, debe configurar su archivo sudoers para permitir que su usuario ejecute el comando elina-tc sin contraseña.

En primer lugar, busque la ruta completa del comando:

# Asegúrese de que su entorno virtual está activo
which elina-tc
# Ejemplo de salida: /home/user/elina-tc-release/venv/bin/elina-tc

A continuación, añada la línea correspondiente al archivo sudoers. Sustituya su_nombre_de_usuario y la ruta de ejemplo por sus datos reales. Utilice sudo visudo para editar /etc/sudoers de forma segura:

su_nombre_de_usuario ALL=(ALL) NOPASSWD: /home/su_nombre_de_usuario/elina-tc-release/venv/bin/elina-tc

Modos de uso (interfaz de línea de comandos)

Una vez instalado, Elina-TC se ejecuta mediante el comando elina-tc. Nota: Todos los comandos que modifican las reglas de red requieren privilegios de sudo.

1. Modo Validate

  • Comprueba si hay errores en los archivos de perfil:
elina-tc --validate -f profiles/satellite/profiles_LEO_Starlink.json

2. Modo On-the-Fly

  • Aplica degradaciones directamente:
elina-tc -i eth0 --onthefly "delay 100ms loss 1%"
  • Esto aplicará 100 ms de retardo y un 1 % de pérdida de paquetes a todo el tráfico que pase por eth0.
  • Los parámetros on-the-fly utilizan las mismas claves que los campos de perfil (consulte Parámetros de perfil más abajo), por ejemplo: delay, jitter, loss, corrupt, rate, duplicate, reorder.

3. Modo Batch

  • Ejecuta secuencias de prueba a partir de perfiles:
elina-tc -i eth0 -f profiles/impairments/profiles_PacketLoss_Degradation.json -n 1 --show-stats
  • Opciones útiles: -n COUNT (número de ciclos), --loop (ejecución continua), --start_at "YYYY-MM-DD HH:MM:SS" (inicio planificado), --dry-run (muestra los comandos tc sin aplicarlos), -d SEC (duración predeterminada por fase). Puede pasar varios archivos -f para encadenar secuencias de perfiles.

4. Modo Interactive

  • Para el control en directo y la depuración:
elina-tc -i eth0 -f profiles/cellular/5g_5qi_profiles.json --interactive

Comandos interactivos (sesión continua):

  • help — lista los comandos disponibles
  • list — muestra todos los perfiles cargados
  • apply <index_or_name> [for Xs] [with stats] — aplica un perfil por índice o por subcadena de la descripción; for 30s opcional borra automáticamente tras X segundos; with stats opcional muestra tc -s tras la aplicación
  • status — muestra las reglas tc en egress e ingress (ifb0)
  • stats [interface] — muestra las estadísticas tc -s detalladas
  • watch stats [interval] — estadísticas en directo, actualizadas cada interval segundos (por defecto: 2); Ctrl+C para detener
  • clear — borra todas las reglas tc de la interfaz y de ifb0
  • exit / quit — sale de la sesión y limpia

La interfaz web (Beta)

Elina-TC incluye una interfaz web complementaria (Beta) que simplifica las operaciones frecuentes sin pasar por la CLI. Después de pip install .[ui] y de la configuración de sudoers anterior:

cd web_ui
python3 elina-tc-ui.py
# Abrir http://127.0.0.1:5000/ en un navegador

Flujo de trabajo típico:

  1. Discover Interfaces — lista los adaptadores; seleccione el que desea degradar.
  2. Browse Profiles — el árbol de perfiles se carga automáticamente; haga clic en un archivo JSON para abrirlo en el editor.
  3. Edit & Save — modifique el JSON en el editor y haga clic en Save para escribirlo en el disco.
  4. Validate — ejecuta las mismas comprobaciones que elina-tc --validate sobre el archivo seleccionado.
  5. Apply — ejecuta todas las fases del archivo de forma secuencial (como el modo Batch), o utilice On-the-Fly para una cadena de degradación puntual.
  6. Stats / Clear — muestra las estadísticas tc -s o elimina las reglas de la interfaz y de ifb0.

Seguridad: No exponga la UI a redes no fiables; realiza operaciones de red privilegiadas mediante sudo. Más detalles en web_ui/README_web_ui.md del paquete.

Trabajar con los perfiles

Los perfiles son archivos JSON o CSV que definen una o varias fases de degradación. Los escenarios preconstruidos se encuentran en profiles/; sus propios escenarios deben ir en profiles/custom/ para no modificar la biblioteca.

Crear un nuevo perfil

  1. Copie una plantilla de profiles/custom/ (o cualquier archivo de la biblioteca) con un nuevo nombre, p. ej. profiles/custom/my_scenario.json.
  2. Modifique los campos (consulte Parámetros de perfil). Un archivo puede ser un objeto único o una tabla de fases para las secuencias en modo Batch.
  3. Valídelo antes de usarlo:
elina-tc --validate -f profiles/custom/my_scenario.json
  1. Aplíquelo (Batch o Interactive):
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json -n 1
# o bien
sudo elina-tc -i eth0 -f profiles/custom/my_scenario.json --interactive

Ejemplo mínimo (una sola fase):

{
  "description": "Flaky 4G Mobile in a Vehicle",
  "duration_sec": "120",
  "rate": "25mbit",
  "delay": "70ms",
  "jitter": "30ms",
  "delay_dist": "normal",
  "loss": "0.8%"
}

Consejo: El paquete incluye una plantilla de prompt de IA en profiles/_prompt-profile-generator/ y un esquema JSON en profiles/schema/elina-tc-profile-schema.json por si desea que un asistente redacte un perfil válido. Ejecute siempre --validate sobre los archivos generados.

Modificar un perfil existente

  • CLI / archivos: Abra el .json o el .csv en un editor, guárdelo y, después, ejecute --validate y vuelva a aplicarlo. Es preferible copiar los archivos de la biblioteca en profiles/custom/ antes de modificarlos.
  • Interfaz web: Seleccione el archivo en el árbol, edítelo en el panel, haga clic en Save y después en Validate / Apply. La UI modifica archivos existentes; no crea nuevos nombres de perfil: créelos primero en el disco (o copie una plantilla).

Parámetros de perfil

Omita cualquier parámetro que no necesite. Las cadenas vacías se ignoran.

Parámetro Ejemplo Notas
description "Congested Wi-Fi" Se muestra para la búsqueda en Interactive list / apply
duration_sec "30" Segundos durante los que esta fase permanece activa en modo Batch
rate "100mbit" Límite de caudal (TBF). Unidades: kbit/mbit/gbit o kbps/mbps/gbps
tbf_burst "128kb" Ráfaga del token bucket; se aplican valores predeterminados si se omite (--default-tbf-burst)
tbf_latency "50ms" Espera máxima en la cola TBF; se aplican valores predeterminados si se omite
delay "100ms" Latencia base (ms/us/s)
jitter "10ms" Variación del retardo — requiere delay
delay_dist "normal" uniform, normal, pareto, paretonormal — requiere jitter
loss "1%" Porcentaje de pérdida de paquetes
loss_correlation "25%" Hace que la pérdida se produzca más en ráfagas — requiere loss
duplicate "0.5%" Duplicación de paquetes
corrupt "0.1%" Corrupción de bits
reorder "5%" Entrega fuera de orden
reorder_correlation "20%" — requiere reorder
reorder_gap "5" Separación en paquetes — requiere reorder
netem_limit "1000" Número máximo de paquetes en la cola netem

Los archivos CSV utilizan los mismos nombres de columna (consulte profiles/custom/custom_profiles.csv). Las líneas de comentario que empiezan por # se ignoran.

La biblioteca de perfiles predefinidos

Elina-TC incluye una amplia biblioteca de perfiles de degradación en el directorio profiles/, organizados por tecnología de red:

  • /basic: Perfiles de ejemplo introductorios y polivalentes; un buen punto de partida.
  • /custom: Ubicación para sus propios perfiles, con plantillas JSON/CSV para copiar.
  • /cellular: Emula las condiciones de las redes móviles. Incluye perfiles para 4G LTE basados en los identificadores de clase QoS (QCI) y para 5G basados en los identificadores QoS 5G (5QI) y en el network slicing (eMBB, URLLC). Perfecto para probar aplicaciones móviles, dispositivos IoT y casos de uso de vehículos conectados (V2X).
  • /satellite: Simula las características únicas de las redes por satélite. Incluye perfiles para las constelaciones en órbita terrestre baja (LEO) como Starlink (baja latencia, rendimiento variable), la órbita terrestre media (MEO) y los satélites geoestacionarios (GEO) tradicionales (latencia elevada y estable). Ideal para aplicaciones marítimas, aeroespaciales e IoT remotas.
  • /wireless: Modela las redes locales inalámbricas habituales. Contiene perfiles para diversas condiciones WiFi (ideales, congestionadas), Bluetooth y redes IoT de bajo consumo, lo que le ayuda a probar aplicaciones en entornos domésticos, de oficina o de dispositivos de corto alcance.
  • /asymmetric: Simula redes con distintas características de subida/bajada (DOCSIS, FTTH, 4G/5G). Como Elina-TC modela de forma simétrica, estos perfiles están pensados para aplicarse una dirección cada vez; consulte la nota sobre el modelado simétrico en Cómo funciona.
  • /industrial: Modela las redes presentes en los entornos de tecnología operativa (OT). Incluye perfiles para protocolos industriales como Profinet, EtherNet/IP y Modbus. Esencial para probar la resiliencia de los sistemas de automatización industrial y SCADA.
  • /impairments: Contiene perfiles genéricos básicos diseñados para probar la resiliencia de las aplicaciones frente a problemas específicos. Incluye secuencias de pérdida de paquetes progresivamente creciente, latencia creciente o la simulación de una ruta de Internet congestionada. Perfecto para identificar los puntos de ruptura de las aplicaciones.

Uso de Elina-TC con un generador de tráfico

Todo el potencial de Elina-TC se aprovecha cuando se utiliza para controlar las condiciones de red del tráfico generado por otra herramienta, como Elina-TG.

  • En la máquina servidor (que ejecuta Elina-TC): Utilice Elina-TC para aplicar una condición de red específica (por ejemplo, una red móvil 5G inestable) a la interfaz de red del servidor.
  • En la máquina cliente (que ejecuta Elina-TG): Utilice Elina-TG para generar una carga de trabajo de aplicación realista (por ejemplo, una simulación de llamada de Zoom) dirigida al servidor.

Esta combinación le permite medir con precisión cómo se comporta su aplicación en escenarios de degradación de red específicos, reproducibles y realistas.

Notas importantes

  • Permisos: Casi todos los comandos elina-tc que modifican la red requieren privilegios de sudo. Nota: Si configuró sudo sin contraseña para elina-tc en el paso 5 de la Configuración anterior, esto no se aplica: no se le pedirá ninguna contraseña.
  • Instantáneas de estado: Antes de modificar una interfaz, Elina-TC guarda automáticamente la configuración tc existente en un archivo de registro con marca de tiempo (elina-tc_state_*.log) en su directorio actual, lo que proporciona un registro de auditoría.
  • Limpieza: Elina-TC está diseñado para limpiar de forma robusta todas sus reglas y dispositivos virtuales cuando finaliza o se interrumpe (Ctrl+C).
  • Uso concurrente: Solo una ejecución de Elina-TC puede controlar una interfaz determinada a la vez (y el dispositivo compartido ifb0). Una segunda ejecución se rechaza con un error claro hasta que finalice la primera. Los archivos de bloqueo se encuentran por defecto en $TMPDIR/elina-tc-locks/ (ELINA_TC_LOCK_DIR para cambiarlo).
  • Documentación detallada: Para la referencia completa de la línea de comandos (elina-tc -h), la tabla de códigos de error y los README del paquete, consulte los archivos incluidos en la distribución.

Resolución de problemas

Síntoma Qué comprobar
elina-tc: command not found Active el entorno virtual (source venv/bin/activate) y confirme la instalación con which elina-tc. Vuelva a ejecutar pip install .[ui] desde la raíz del paquete si es necesario.
Permiso denegado / se pide la contraseña cada vez Los modos de aplicación requieren sudo. Para la interfaz web (y la CLI sin contraseña), configure la entrada de sudoers con la ruta completa devuelta por which elina-tc.
Errores de validación de perfil (EC1004–EC1010) Ejecute elina-tc --validate -f <archivo>. Causas frecuentes: unidades incorrectas (100ms y no 100), jitter sin delay, loss_correlation sin loss, porcentaje fuera de 0–100. Corrija el índice/descripción indicado y vuelva a validar.
Parámetro on-the-fly desconocido (EC1003) Utilice las mismas claves que los parámetros de perfil (p. ej. delay 50ms loss 1%). Los valores deben ir detrás de cada clave.
Interfaz ya en uso (EC3001) / conflicto con ifb0 compartido Otro proceso de Elina-TC (sesión CLI o apply de la Web UI) mantiene todavía el bloqueo. Salga de esa sesión o bórrela primero. Los bloqueos obsoletos de un proceso terminado suelen recuperarse automáticamente; archivos en $TMPDIR/elina-tc-locks/.
Fallo de tc / ip / modprobe (EC2001) Compruebe que está en Linux con iproute2 instalado, que el nombre de la interfaz es correcto (ip link) y que el módulo ifb puede cargarse (sudo modprobe ifb).
RTT medido ≈ 2× el delay del perfil Es lo esperado: el modelado es simétrico. delay: "50ms" añade ~50 ms en cada sentido (~100 ms de RTT).
La interfaz web no puede aplicar / falla el guardado Confirme pip install .[ui], que sudoers está configurado y que la UI está abierta en el host (http://127.0.0.1:5000/). No exponga la UI a redes no fiables.
Reglas restantes tras un fallo Ejecute sudo elina-tc -i <iface> --interactive clear. Elina-TC limpia normalmente al salir o con Ctrl+C.

Los errores se marcan con códigos estables como [EC2001]. La tabla completa está en documentation/ERROR_CODES.md del paquete; al ponerse en contacto con el soporte, incluya el código ECnnnn y el comando ejecutado.