proxmox-adguard-sync
Servicio en Go para sincronizar direcciones IPv4 de invitados Proxmox VE (VMs y LXC) con reescrituras DNS en AdGuard Home. Soporta descubrimiento estático, DHCP y metadata. Incluye modo dry-run por defecto y protección de registros manuales. Pre-release.
Ficha actualizada 28 sept 2026, 11:46 · upstream 28 sept 2026, 11:35 · release sin release detectada
Qué es proxmox-adguard-sync
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
proxmox-adguard-sync es una herramienta escrita en Go que automatiza la sincronización de direcciones IPv4 de máquinas virtuales QEMU/KVM y contenedores LXC con el servicio DNS AdGuard Home. El software descubre las IPs mediante agentes invitados, configuración cloud-init o metadatos estáticos en la descripción del invitado, permitiendo reescrituras DNS dinámicas sin intervención manual constante.
La aplicación opera mediante ciclos de conciliación continuos que comparan el inventario actualizado de Proxmox con los registros existentes en AdGuard Home. Gestiona operaciones de añadir, actualizar o eliminar reescrituras basándose en un estado persistente local, protegiendo explícitamente las entradas DNS creadas manualmente para evitar borrados accidentales.
El proyecto se encuentra actualmente en fase pre-release y bajo desarrollo activo. Aunque la implementación original en JavaScript está disponible en una rama legacy, el código principal utiliza Go 1.24 o superior. No incluye soporte nativo para contenedores Docker ni orquestación con Compose, requiriendo compilación local o ejecución directa del binario generado.
- Automatizar la gestión de DNS interno en entornos Proxmox VE sin intervención manual constante
- Sincronizar direcciones IP dinámicas de invitados QEMU/KVM y LXC con AdGuard Home
- Implementar políticas de filtrado DNS basadas en etiquetas o estados de invitados Proxmox
- Mantener un registro persistente de la propiedad de las reescrituras DNS para evitar conflictos
- Ejecutar pruebas de cambios DNS en modo dry-run antes de aplicar modificaciones en producción
- Modo dry-run habilitado por defecto para validar planes de conciliación sin modificar datos
- Protección automática de reescrituras DNS manuales creadas fuera del alcance de la herramienta
- Soporte nativo para descubrimiento de IP vía QEMU Guest Agent, cloud-init y configuración LXC
- Arquitectura ligera en Go sin dependencias externas, ejecutable como binario único
- Persistencia del estado de propiedad en archivo JSON local para conciliación robusta
- Software pre-release sin validación completa para entornos de producción según documentación oficial
- Requiere configuración manual de variables de entorno y no carga automáticamente archivos .env
- No incluye soporte nativo para Docker, Compose o despliegue en contenedores modernos
- Dependencia de Go 1.24 o superior para compilación local, lo que puede limitar compatibilidad con versiones antiguas
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Compilar el binario con go build y ejecutar directamente. Configurar variables de entorno PROXMOX_BASE_URL, ADGUARD_BASE_URL y credenciales antes de iniciar. Mantener DRY_RUN=true durante la evaluación inicial. Asegurar acceso API a Proxmox VE y red hacia AdGuard Home. Guardar estado en ./data/state.json.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.