FAQ & Solución de problemas

El agente ha arrancado correctamente pero el código de registro aún no se ha introducido en rud1-es. Para completar el registro:

1. Obtén el código de registro del dispositivo (ver pregunta siguiente)
2. En rud1-es, ve a Dispositivos → Añadir dispositivo
3. Introduce el código y asigna un nombre al dispositivo
4. El estado cambiará a ONLINE en unos segundos

Hay dos formas de obtenerlo:

Opción 1 — Logs del agente:

journalctl -u rud1-agent -f | grep registration_code
# Salida: registration_code="RUD1-ABCD-1234"

Opción 2 — Panel local:

Accede a http://[ip-del-dispositivo] desde tu red local. El código aparece en la pantalla principal del panel rud1-app.

El código de registro introducido en rud1-es no coincide con el generado por el agente. Causas comunes:

• Copiaste el código incorrectamente (es sensible a mayúsculas)
• No incluiste el prefijo RUD1-
• El agente se reinició y generó un nuevo código

Obtén el código actual de los logs con el comando de arriba y vuelve a intentarlo.

Diagnostica el problema con estos comandos:

# Ver estado del servicio
systemctl status rud1-agent

# Ver logs recientes
journalctl -u rud1-agent --since "5 minutes ago"

Causas habituales:

• api_secret faltante o vacío en config.yaml
• Sintaxis inválida en el archivo YAML (indentación incorrecta)
• Permisos incorrectos en los directorios /var/lib/rud1-agent
• El binario no tiene permisos de ejecución

• Verifica que cloud.api_secret está correctamente configurado en config.yaml
• Comprueba la conectividad a internet desde el dispositivo: ping 8.8.8.8
• El intervalo de heartbeat por defecto es 60 segundos. El dispositivo puede aparecer OFFLINE hasta que envíe su primer heartbeat. Espera 60-90 segundos.
• Revisa los logs: journalctl -u rud1-agent -f | grep heartbeat

Sigue este proceso de diagnóstico:

# 1. Verificar que WireGuard está instalado
which wg-quick

# 2. Ver el estado actual de la interfaz
sudo wg show

# 3. Comprobar el archivo de configuración
cat /etc/wireguard/wg0.conf

# 4. Intentar conectar manualmente
sudo wg-quick up wg0

# 5. Verificar que el servidor es alcanzable (cambia el puerto si usas otro)
nc -uzv vpn.tuservidor.com 51820

# Verificar que WireGuard está corriendo en el servidor
sudo wg show

# Verificar que el puerto UDP 51820 está abierto
sudo ufw status

Esto suele ocurrir cuando el dispositivo está detrás de un NAT estricto. Añade PersistentKeepalive = 25 en la sección [Peer] del archivo /etc/wireguard/wg0.conf del dispositivo:

[Peer]
PublicKey = <SERVER_PUBLIC_KEY>
Endpoint = vpn.tuempresa.com:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

Después recarga la configuración: sudo wg-quick down wg0 && sudo wg-quick up wg0

Comprueba en orden:

1. Verifica que nginx (o el servidor que sirve rud1-app) está corriendo: systemctl status nginx
2. Verifica que el puerto 80 no está bloqueado por el firewall del dispositivo: sudo ufw allow 80
3. Intenta acceder directamente con la IP: http://192.168.x.x
4. Asegúrate de que tu navegador y el dispositivo están en la misma red local (o conectados via VPN)
5. Prueba desde el propio dispositivo: curl http://localhost

rud1-app no puede conectarse al agente rud1-fw en el puerto 7070. Diagnostica el agente:

# Ver estado del agente
systemctl status rud1-agent

# Probar la API local directamente
curl http://localhost:7070/health
# Respuesta esperada: {"status":"ok"}

Si el agente no responde, reinícialo: sudo systemctl restart rud1-agent

# Ver logs relacionados con firmware
journalctl -u rud1-agent | grep firmware

# Verificar espacio en disco
df -h /

# Verificar que el directorio temporal es escribible
ls -la /tmp/

Causas comunes:

• El checksum SHA256 no coincide (archivo descargado corrupto) — el agente reintentará automáticamente
• Disco lleno — libera espacio y reinicia el agente
• Permisos incorrectos en el directorio de instalación
• Conexión a internet interrumpida durante la descarga

La comprobación de firmware se realiza cada 10 minutos. Espera hasta 10 minutos desde que creaste el rollout. Si transcurrido ese tiempo no hay actualización:

• Verifica que el dispositivo está ONLINE en rud1-es
• Reinicia el agente para forzar una comprobación inmediata: sudo systemctl restart rud1-agent
• Comprueba que el rollout está activo y dirigido al dispositivo correcto en rud1-es → Firmware → detalle del rollout
• Verifica en los logs: journalctl -u rud1-agent | grep "firmware"

1. Verifica que la URL del webhook es correcta en la configuración de la regla de alerta
2. Comprueba que la URL es accesible desde los servidores de rud1-es (no puede ser localhost ni una IP interna de tu red)
3. Prueba el webhook desde Configuración → Webhooks → Probar
4. Verifica que la regla de alerta está habilitada
5. Comprueba los logs de entrega del webhook en el historial de alertas

El intervalo de heartbeat por defecto es 60 segundos. Las métricas se actualizan con cada heartbeat. Si transcurrido 90+ segundos las métricas siguen sin cambiar:

• Verifica que el dispositivo está ONLINE
• Comprueba que los heartbeats se están enviando: journalctl -u rud1-agent | grep heartbeat
• Recarga la página del dashboard (puede haber un problema de caché del navegador)

La forma recomendada es usar el sistema de gestión de firmware de rud1-es (subir versión + crear rollout). Consulta la guía de gestión de firmware.

Para actualización manual de emergencia:

sudo systemctl stop rud1-agent
# Sustituye el binario:
sudo cp nuevo-rud1-agent /usr/local/bin/rud1-agent
sudo chmod +x /usr/local/bin/rud1-agent
sudo systemctl start rud1-agent

Un factory reset elimina el token de dispositivo guardado, lo que fuerza al agente a generar un nuevo código de registro:

sudo systemctl stop rud1-agent
sudo rm /var/lib/rud1-agent/device.json
sudo systemctl start rud1-agent
# El agente generará un nuevo código de registro

El dispositivo antiguo en rud1-es quedará marcado como OFFLINE y puedes eliminarlo manualmente desde Dispositivos → [dispositivo] → Eliminar.

• Plan Free: hasta 3 dispositivos
• Plan Pro: hasta 25 dispositivos
• Plan Enterprise: dispositivos ilimitados

Puedes ver y cambiar tu plan en Configuración → Facturación.

No. El agente rud1-fw solo realiza conexiones salientes mediante HTTPS hacia rud1-es. El dispositivo puede estar detrás de NAT, CGNAT o cualquier firewall que permita tráfico saliente por el puerto 443.

La VPN WireGuard sí requiere que el servidor VPN (hub) tenga una IP pública y el puerto UDP 51820 accesible. El dispositivo en sí no necesita IP pública para la VPN.

Si no encuentras respuesta en esta documentación, contacta con nuestro equipo:

• Email: support@rud1.es
• Para reportar bugs o problemas de seguridad, por favor incluye los logs del agente y los pasos para reproducir el problema.