Resolución de Problemas

⏱ Sesión expirada — no puedo acceder a recursos

Las sesiones tienen una duración limitada (normalmente 4–8 horas). Cuando tu sesión expira, el handshake de WireGuard falla y pierdes acceso a los recursos internos.

Síntomas:

• El ping a hosts internos da timeout
• El TUI muestra "conectado" pero los bytes transferidos dejan de aumentar
• wireztna status muestra un handshake obsoleto (>5 minutos)

Solución:

# El cliente renueva automáticamente, pero si falló puedes forzarlo:
wireztna disconnect
wireztna connect

El comando connect solicita automáticamente una sesión nueva. Si tu token de login también expiró, se te pedirá iniciar sesión de nuevo.

🔄 Conexión caída — cómo reconectar

Si tu red cambió (cambio de Wi-Fi, suspensión/despertar, cerrar la tapa del portátil), el túnel puede necesitar reestablecerse.

Solución rápida:

# Desconectar limpiamente y reconectar
sudo wireztna disconnect
sudo wireztna connect

Usando el TUI:

# El TUI reconecta automáticamente en cambios de red
sudo wireztna tui
# Pulsa 'd' para desconectar, luego 'c' para reconectar

Usando la app de bandeja (Windows/macOS):

Haz clic derecho en el icono de bandeja → Desconectar → Conectar. La app de bandeja gestiona la renovación de sesión automáticamente.

💻 He cambiado de dispositivo

Cada dispositivo necesita su propio enrollment. Tu clave privada WireGuard es única por dispositivo y nunca sale de él.

Pasos:

1. Pide a tu administrador que genere un nuevo token de enrollment (o genera uno desde el portal de autoservicio si está habilitado)
2. En el nuevo dispositivo:

   wireztna enroll "https://tu-broker/api/v1/clients/enroll?token=..."
   wireztna login
   sudo wireztna connect

3. El dispositivo antiguo dejará de funcionar una vez enrolles el nuevo (cada usuario tiene una clave activa)

🔑 Re-enrollment desde cero

Si tu configuración está corrupta, cambiaste tu email, o el enrollment falló a medias, puedes necesitar un re-enrollment limpio.

macOS / Linux:

# 1. Eliminar la configuración existente
rm -rf ~/.wireztna

# 2. Obtener un nuevo token de enrollment de tu administrador

# 3. Enrollar de nuevo
wireztna enroll "https://tu-broker/api/v1/clients/enroll?token=NUEVO_TOKEN"
wireztna login
sudo wireztna connect

Windows:

# 1. Eliminar configuración existente (PowerShell)
Remove-Item -Recurse -Force "$env:USERPROFILE\.wireztna"

# 2. Obtener un nuevo token de enrollment de tu administrador

# 3. Enrollar de nuevo
wireztna enroll "https://tu-broker/api/v1/clients/enroll?token=NUEVO_TOKEN"
wireztna login
wireztna connect

⚠ Muestra "conectado" pero nada funciona

La interfaz del túnel está activa, la IP asignada, pero no puedes acceder a ningún recurso. La transferencia muestra 0 bytes.

Causa más común: desajuste de claves tras re-enrollment

Esto ocurre cuando enrollaste dos veces (ej., error de token la primera vez) y el broker tiene una clave pública diferente a la de tu config local.

Diagnóstico rápido:

# Comprueba si tienes handshake
wireztna status

# Si "latest handshake: never" o muy antiguo → el broker no reconoce tu clave
# Solución: re-enroll limpio (ver sección anterior)

Otras posibles causas:

• Sesión expirada — ejecuta wireztna disconnect && wireztna connect
• Publisher offline — pide a tu administrador que compruebe el estado del publisher
• Firewall bloqueando UDP — WireGuard necesita UDP de salida al puerto 51820 (ver Requisitos)
• Problemas de MTU (Windows) — actualiza a la última versión del cliente (corregido en v0.9.2+)

🌐 DNS interno no resuelve

Puedes hacer ping a IPs pero los nombres internos (ej., db.compute.internal) no resuelven.

Comprueba tu configuración DNS:

# macOS — verificar que el resolver está registrado
scutil --dns | grep -A3 "compute.internal"

# Linux — comprobar systemd-resolved
resolvectl status | grep -A3 "wireztna"

# Windows — comprobar reglas NRPT
Get-DnsClientNrptRule | Where-Object { $_.DisplayName -like "WireZTNA:*" }

Soluciones comunes:

• Reconectar — Las reglas DNS se aplican al conectar. Desconecta y conecta de nuevo.
• macOS: dig/nslookup no funcionan — Es comportamiento esperado. Estas herramientas saltan los resolvers de macOS. Usa dig @10.200.0.1 hostname.zona para probar explícitamente, o simplemente usa ping hostname.zona que usa el resolver del sistema.
• Zona no configurada — Pregunta a tu administrador si la zona DNS está configurada en el publisher.

🖥 La app de bandeja no conecta (Windows)

El icono de bandeja aparece pero al hacer clic en "Conectar" no pasa nada o muestra un error.

Causas comunes y soluciones:

• UAC no aceptado: El proceso helper necesita elevación. Cuando haces clic en Conectar, deberías ver un prompt UAC. Si lo descartaste, inténtalo de nuevo.
• Helper ya en ejecución: Comprueba en el Administrador de tareas si hay procesos wireztna.exe. Ciérralos todos y reintenta.
• No enrollado: Abre un terminal y ejecuta wireztna status. Si dice "not enrolled", necesitas enrollar primero.
• Antivirus bloqueando: Algunos antivirus (Kaspersky, ESET) bloquean el driver wintun. Añade wireztna.exe a las exclusiones.

Conexión manual como alternativa:

# Abre PowerShell como Administrador
wireztna connect

# Si esto funciona pero la bandeja no → problema de IPC bandeja/helper
# Reinicia la app de bandeja desde el Menú Inicio

🔀 Cambiar entre proyectos / grupos

Si perteneces a múltiples grupos que tienen redes solapadas, puede que necesites seleccionar por qué proyecto enrutar.

Usando la CLI:

# Seleccionar un proyecto específico
sudo wireztna connect -g nombre-proyecto

# O seleccionar "all" para acceder a todo (con posible ambigüedad de routing)
sudo wireztna connect -g all

Usando el TUI:

# Abrir TUI
sudo wireztna tui

# Pulsa Tab → pestaña Proyectos
# Pulsa 0 para "Todos los grupos" o 1-9 para seleccionar un proyecto
# Pulsa 'c' para conectar con la selección

Cambiar de proyecto fuerza una renovación de sesión. Tu sesión anterior se desactiva y se crea una nueva con las reglas de enrutamiento correctas.

🌍 Modo VPN / exit node no funciona

Si tu administrador habilitó el modo VPN para tu cuenta, puedes enrutar todo el tráfico a través de un publisher (túnel completo).

Prerrequisitos:

• Tu usuario debe tener vpn_mode = true (el admin lo habilita)
• Al menos un publisher debe estar marcado como exit node
• Ese publisher debe estar en un grupo asignado a ti

Conectar en modo VPN:

# CLI — especificar exit node
sudo wireztna connect --exit-node nombre-publisher

# TUI — la pestaña Proyectos muestra exit nodes cuando el modo VPN está habilitado
# Selecciona la ubicación y pulsa 'c'

# Para volver a split tunnel:
sudo wireztna connect --split

Si el modo VPN conecta pero internet no funciona:

• Comprueba que el publisher tiene acceso a internet (necesita hacer masquerade de tu tráfico)
• Prueba otra ubicación de exit node si está disponible
• Verifica con wireztna status que el handshake es reciente

✔ Cómo comprobar el estado de tu conexión

La forma más rápida de diagnosticar qué está pasando:

# Comprobación rápida de estado
wireztna status

# La salida muestra:
#   Enrolled: yes/no
#   Tunnel: up/down
#   Overlay IP: 10.200.x.x
#   Handshake: Xs ago (debería ser < 150s)
#   Transfer: rx / tx bytes (debería aumentar)
#   Session: active / expired
#   Project: nombre-proyecto o "all"

Qué buscar:

🪧 Windows

Desinstalación completa (antes de actualizar o solucionar problemas)

# 1. Desconectar el túnel (si está conectado)
wireztna disconnect

# 2. Eliminar reglas DNS NRPT (PowerShell como Admin)
Get-DnsClientNrptRule | Where-Object { $_.DisplayName -like "WireZTNA:*" } | Remove-DnsClientNrptRule -Force

# 3. Desinstalar el MSI (PowerShell como Admin)
# Opción A: vía Configuración → Aplicaciones → WireZTNA → Desinstalar
# Opción B: vía línea de comandos
msiexec /x "{PRODUCT-CODE}" /quiet
# O buscar por nombre:
Get-WmiObject Win32_Product | Where-Object { $_.Name -like "*WireZTNA*" } | ForEach-Object { $_.Uninstall() }

# 4. Eliminar config del usuario (opcional — solo si haces re-enrollment limpio)
Remove-Item -Recurse -Force "$env:USERPROFILE\.wireztna"

# 5. Matar procesos residuales
Get-Process wireztna* -ErrorAction SilentlyContinue | Stop-Process -Force

Actualizar a una nueva versión

# 1. Desconectar primero
wireztna disconnect

# 2. Instalar el nuevo MSI (sobreescribe la versión anterior)
msiexec /i wireztna-X.Y.Z-windows-amd64.msi /quiet

# 3. Reconectar
wireztna connect

# Tu config (~\.wireztna\config.yaml) se preserva entre actualizaciones.
# No necesitas re-enrollar.

Verificar la instalación

# Comprobar versión
wireztna --version

# Comprobar el adaptador del túnel
Get-NetAdapter | Where-Object { $_.InterfaceDescription -like "*wintun*" -or $_.Name -like "*wireztna*" }

# Comprobar reglas NRPT activas (split DNS)
Get-DnsClientNrptRule | Where-Object { $_.DisplayName -like "WireZTNA:*" }

# Comprobar que el proceso helper está en ejecución
Get-Process wireztna -ErrorAction SilentlyContinue

Problemas conocidos en Windows

• Aviso de SmartScreen en la primera instalación: El MSI puede mostrar "Windows protegió tu equipo". Haz clic en "Más información" → "Ejecutar de todas formas". Esto desaparecerá cuando tengamos un certificado de firma EV.
• El antivirus pone wireztna.exe en cuarentena: Añade una exclusión para C:\Program Files\WireZTNA\ en tu antivirus.
• Prompt UAC cada vez que conectas: Es por diseño — el helper necesita elevación para crear el adaptador de túnel. Añade tu usuario al grupo "Network Configuration Operators" vía GPO para evitarlo.
• Error de wintun.dll: Actualiza al último MSI (v0.9.2+). Las versiones antiguas requerían una instalación separada de WireGuard.

🍎 macOS

Instalar

# Prerrequisitos: wireguard-go y wireguard-tools
brew install wireguard-go wireguard-tools

# Descargar el binario para tu arquitectura (Intel o Apple Silicon)
# Desde la página de descargas de tu admin o:
curl -fsSL https://tu-broker/downloads/wireztna-darwin-arm64 -o /usr/local/bin/wireztna
chmod +x /usr/local/bin/wireztna

Desinstalación completa

# 1. Desconectar
sudo wireztna disconnect

# 2. Eliminar el binario
sudo rm /usr/local/bin/wireztna

# 3. Eliminar archivos de resolver de split DNS
sudo rm -f /etc/resolver/compute.internal  # repetir para cada zona

# 4. Eliminar config del usuario (opcional — solo si haces re-enrollment limpio)
rm -rf ~/.wireztna

Actualizar a una nueva versión

# 1. Desconectar
sudo wireztna disconnect

# 2. Reemplazar el binario
curl -fsSL https://tu-broker/downloads/wireztna-darwin-arm64 -o /usr/local/bin/wireztna
chmod +x /usr/local/bin/wireztna

# 3. Reconectar
sudo wireztna connect

# La config se preserva. No necesitas re-enrollar.

Problemas conocidos en macOS

• "no se puede abrir porque el desarrollador no puede ser verificado": Haz clic derecho → Abrir → Abrir. O ejecuta: xattr -d com.apple.quarantine /usr/local/bin/wireztna
• dig/nslookup no resuelven nombres internos: Comportamiento esperado — estas herramientas saltan los resolvers de macOS. Usa ping hostname.zona o dig @10.200.0.1 hostname.zona.
• Requiere sudo cada vez que conectas: macOS necesita root para crear interfaces de red. Un helper con privilegios (auto-sudo) está previsto para una versión futura.

🐧 Linux

Instalar

# Descargar el binario
curl -fsSL https://tu-broker/downloads/wireztna-linux-amd64 -o /usr/local/bin/wireztna
chmod +x /usr/local/bin/wireztna

# Opcional: permitir ejecución sin sudo (una sola vez)
sudo setcap 'cap_net_admin+ep cap_net_raw+ep' /usr/local/bin/wireztna

Desinstalación completa

# 1. Desconectar
sudo wireztna disconnect

# 2. Eliminar interfaz WireGuard (si sigue presente)
sudo ip link del wg-wireztna 2>/dev/null

# 3. Eliminar el binario
sudo rm /usr/local/bin/wireztna

# 4. Limpiar split DNS de systemd-resolved (si aplica)
sudo resolvectl revert wg-wireztna 2>/dev/null

# 5. Eliminar config del usuario (opcional — solo si haces re-enrollment limpio)
rm -rf ~/.wireztna

Actualizar a una nueva versión

# 1. Desconectar
sudo wireztna disconnect

# 2. Reemplazar binario
sudo curl -fsSL https://tu-broker/downloads/wireztna-linux-amd64 -o /usr/local/bin/wireztna
sudo chmod +x /usr/local/bin/wireztna

# 3. Reaplicar capabilities si usas modo sin root
sudo setcap 'cap_net_admin+ep cap_net_raw+ep' /usr/local/bin/wireztna

# 4. Reconectar
sudo wireztna connect

# La config se preserva. No necesitas re-enrollar.

Problemas conocidos en Linux

• sudo resetea HOME a /root: Corregido en v0.4.5+. Si usas una versión anterior, ejecuta sudo -E wireztna connect para preservar tu directorio home.
• Módulo WireGuard del kernel no cargado: En algunas distribuciones, ejecuta sudo modprobe wireguard primero. El kernel 5.6+ tiene WireGuard integrado.
• systemd-resolved no disponible: En sistemas sin systemd-resolved (Alpine, Debian antiguo), el split DNS no funcionará automáticamente. Añade las entradas DNS manualmente a /etc/resolv.conf o usa resolvconf.
• Permiso denegado sin sudo: Aplica capabilities: sudo setcap 'cap_net_admin+ep cap_net_raw+ep' /usr/local/bin/wireztna