{"id":31794316,"url":"https://github.com/jeeftor/dhcp-adguard-sync","last_synced_at":"2025-10-10T19:27:29.122Z","repository":{"id":271929110,"uuid":"915010890","full_name":"jeeftor/dhcp-adguard-sync","owner":"jeeftor","description":"Sync leases one way from OPNSense ISC to AdguardHome","archived":false,"fork":false,"pushed_at":"2025-09-20T02:09:57.000Z","size":6565,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-09-20T03:32:48.532Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeeftor.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-01-10T19:16:28.000Z","updated_at":"2025-09-19T20:26:57.000Z","dependencies_parsed_at":"2025-01-10T20:29:12.796Z","dependency_job_id":"0ee078bf-fd8b-479c-9440-f656101b2f9b","html_url":"https://github.com/jeeftor/dhcp-adguard-sync","commit_stats":null,"previous_names":["jeeftor/opnsense-lease-sync","jeeftor/dhcp-adguard-sync"],"tags_count":52,"template":false,"template_full_name":null,"purl":"pkg:github/jeeftor/dhcp-adguard-sync","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeeftor%2Fdhcp-adguard-sync","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeeftor%2Fdhcp-adguard-sync/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeeftor%2Fdhcp-adguard-sync/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeeftor%2Fdhcp-adguard-sync/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeeftor","download_url":"https://codeload.github.com/jeeftor/dhcp-adguard-sync/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeeftor%2Fdhcp-adguard-sync/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279005037,"owners_count":26083827,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-10T02:00:06.843Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-10T19:27:28.028Z","updated_at":"2025-10-10T19:27:29.115Z","avatar_url":"https://github.com/jeeftor.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DHCP AdGuard Sync for OPNsense\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/jeeftor/opnsense-lease-sync)](https://golang.org/)\n[![Release](https://img.shields.io/github/v/release/jeeftor/opnsense-lease-sync)](https://github.com/jeeftor/opnsense-lease-sync/releases)\n[![License](https://img.shields.io/github/license/jeeftor/opnsense-lease-sync)](LICENSE)\n\n\u003e **Automatically sync DHCP clients from OPNsense to AdGuard Home for seamless DNS filtering**\n\nEver notice that devices on your network don't show up by name in AdGuard Home? This service solves that by automatically synchronizing DHCP lease information from OPNsense to AdGuard Home, ensuring all your devices are properly identified for DNS filtering and monitoring.\n\n## ✨ What This Solves\n\n- **📱 Device Recognition**: See device names instead of IP addresses in AdGuard Home\n- **🔄 Automatic Sync**: No manual client configuration in AdGuard Home\n- **📊 Better Analytics**: Proper device identification for detailed statistics\n- **🛡️ Enhanced Filtering**: Apply DNS rules based on device names\n\n## 🚀 Quick Start\n\n**One-line installation:**\n```bash\ncurl -sSL https://raw.githubusercontent.com/jeeftor/opnsense-lease-sync/master/install.sh | sh\n```\n\n**Then configure via OPNsense Web UI:**\n1. Navigate to **Services \u003e DHCP AdGuard Sync**\n2. Enter your AdGuard Home credentials\n3. Select your DHCP server type (DNSMasq is default)\n4. Click **Save** - service auto-restarts!\n\n**That's it!** Your DHCP clients will now appear in AdGuard Home.\n\n## Architecture\n\nThis project consists of two main components:\n\n1. **Main Application** (`dhcp-adguard-sync`): A Go-based service that handles the actual synchronization\n2. **OPNsense Plugin**: A web UI plugin that integrates with OPNsense for easy configuration and management\n\nThe plugin provides a user-friendly interface within OPNsense while the main application handles the core functionality.\n\n## 🎯 Features\n\n| Feature | Description |\n|---------|-------------|\n| 🔄 **Auto-Sync** | Real-time DHCP lease monitoring and synchronization |\n| 🖥️ **Web UI** | Native OPNsense plugin for easy configuration |\n| 🏷️ **Device Names** | See friendly hostnames instead of IP addresses |\n| 📡 **IPv6 Support** | Handles both IPv4 and IPv6 via NDP table monitoring |\n| ⚙️ **Multi-Format** | Supports both ISC DHCP and DNSMasq lease formats |\n| 🧪 **Test Mode** | Dry-run capability for safe testing |\n| 📝 **Logging** | Configurable log levels with rotation |\n| 🚀 **Service** | Runs as native FreeBSD service |\n\n## 📋 Prerequisites\n\n- ✅ OPNsense firewall\n- ✅ AdGuard Home installed and running\n- ✅ AdGuard Home admin credentials\n- ✅ Root access to OPNsense (for installation)\n\n## 💾 Installation\n\n\u003e **💡 Pro Tip**: The automatic installation is recommended for most users\n\n### 🚀 Option 1: Automatic Installation (Recommended)\n\nInstall both components with a single command:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/jeeftor/opnsense-lease-sync/master/install.sh | sh\n```\n\nThis script will:\n- Download the latest release for your platform\n- Install the main application binary and service\n- Install the OPNsense plugin (if running on OPNsense)\n- Set up initial configuration\n\n### Option 2: Manual Installation\n\n#### Step 1: Install Main Application\n\n1. **Download the binary** from the [releases page](https://github.com/jeeftor/opnsense-lease-sync/releases):\n   ```bash\n   # Example for FreeBSD amd64\n   curl -L -o dhcp-adguard-sync.tar.gz \\\n     \"https://github.com/jeeftor/opnsense-lease-sync/releases/download/v0.0.26/dhcp-adguard-sync_freebsd_amd64_v0.0.26.tar.gz\"\n   tar -xzf dhcp-adguard-sync.tar.gz\n   ```\n\n2. **Install on your OPNsense system**:\n   ```bash\n   # Copy binary to OPNsense\n   scp dhcp-adguard-sync root@opnsense:/root/\n\n   # SSH and install\n   ssh root@opnsense\n   cd /root\n   chmod +x dhcp-adguard-sync\n   ./dhcp-adguard-sync install --username \"your-adguard-username\" --password \"your-adguard-password\"\n   ```\n\n3. **Start and enable the service**:\n   ```bash\n   service dhcp-adguard-sync start\n   service dhcp-adguard-sync enable\n   ```\n\n#### Step 2: Install OPNsense Plugin (Optional)\n\nThe plugin provides a web UI for easy configuration and management.\n\n1. **Download the plugin package**:\n   ```bash\n   curl -L -o os-dhcpadguardsync-plugin.tar.gz \\\n     \"https://github.com/jeeftor/opnsense-lease-sync/releases/download/v0.0.26/os-dhcpadguardsync-plugin.tar.gz\"\n   ```\n\n2. **Extract and install the plugin**:\n   ```bash\n   tar -xzf os-dhcpadguardsync-plugin.tar.gz\n   cd opnsense-plugin/src\n   cp -r opnsense/* /usr/local/opnsense/\n   ```\n\n3. **Clear OPNsense caches**:\n   ```bash\n   rm -f /tmp/opnsense_menu_cache.xml\n   rm -f /tmp/opnsense_acl_cache.json\n   service configd restart\n   service php-fpm restart\n   ```\n\n### Configuration Options\n\nAfter installation, you can configure the service:\n\n- **Via OPNsense Web UI** (if plugin installed): Navigate to Services \u003e DHCP AdGuard Sync\n- **Via command line**: Edit `/usr/local/etc/dhcp-adguard-sync/config.yaml`\n- **Via CLI commands**: Use `dhcp-adguard-sync --help` for options\n\n## Configuration\n\nThe configuration file is located at `/usr/local/etc/dhcp-adguard-sync/config.yaml`.\n\n### Lease Format Selection\n\nThis application supports both ISC DHCP and DNSMasq lease formats:\n\n- **Important**: DNSMasq is now the default DHCP server in OPNsense\n- Choose the lease format that matches your DHCP server configuration\n- The selected lease file is monitored for changes in real-time\n- When the file changes, a synchronization is triggered automatically\n- The application will parse the lease file according to the selected format\n\n#### DNSMasq Configuration (Default in OPNsense)\n\nIf you're using DNSMasq (the default in current OPNsense versions), make sure to set:\n```yaml\nLEASE_FORMAT=\"dnsmasq\"\nDHCP_LEASE_PATH=\"/var/db/dnsmasq.leases\"\n```\n\n#### ISC DHCP Configuration (Legacy)\n\nIf you're using the older ISC DHCP server:\n```yaml\nLEASE_FORMAT=\"isc\"\nDHCP_LEASE_PATH=\"/var/dhcpd/var/db/dhcpd.leases\"\n```\n\nKey configuration options:\n```yaml\n# AdGuard Home credentials\nADGUARD_USERNAME=\"admin\"\nADGUARD_PASSWORD=\"password\"\n\n# AdGuard Home connection settings\nADGUARD_URL=\"127.0.0.1:3000\"\nADGUARD_SCHEME=\"http\"\n\n# DHCP lease file configuration\nDHCP_LEASE_PATH=\"/var/db/dnsmasq.leases\"            # Path to the DNSMasq lease file (default in OPNsense)\nLEASE_FORMAT=\"dnsmasq\"                             # Lease format: \"dnsmasq\" or \"isc\"\n\n# Legacy ISC DHCP configuration (commented out for reference)\n#DHCP_LEASE_PATH=\"/var/dhcpd/var/db/dhcpd.leases\"   # Path to the ISC DHCP lease file\n#LEASE_FORMAT=\"isc\"                                # For ISC DHCP server\n\n# Optional settings\n#PRESERVE_DELETED_HOSTS=\"false\"\n#DEBUG=\"false\"\n#DRY_RUN=\"false\"\nADGUARD_TIMEOUT=\"10\"\n\n# Logging configuration\nLOG_LEVEL=\"info\"\nLOG_FILE=\"/var/log/dhcp-adguard-sync.log\"\n```\n\n## Usage\n\n### Service Management\n\nStart the service:\n```bash\nservice dhcp-adguard-sync start\n```\n\nStop the service:\n```bash\nservice dhcp-adguard-sync stop\n```\n\nCheck status:\n```bash\nservice dhcp-adguard-sync status\n```\n\n### View Logs\n\nVia OPNsense UI:\n1. Navigate to System \u003e Log Files\n2. Select \"General\" tab\n3. Look for entries from \"dhcp-adguard-sync\"\n\nVia command line:\n```bash\n# View service log file\ntail -f /var/log/dhcp-adguard-sync.log\n\n# View system log entries\ngrep dhcp-adguard-sync /var/log/messages\n```\n\n### Manual Sync\n\nTo perform a one-time sync with ISC DHCP lease format (default):\n```bash\ndhcp-adguard-sync sync --username \"your-username\" --password \"your-password\" --lease-path \"/var/dhcpd/var/db/dhcpd.leases\"\n```\n\nTo perform a one-time sync with DNSMasq lease format:\n```bash\ndhcp-adguard-sync sync --username \"your-username\" --password \"your-password\" --lease-path \"/var/db/dnsmasq.leases\" --lease-format \"dnsmasq\"\n```\n\nThe application will read the lease file using the specified format and synchronize all clients to AdGuard Home.\n\n### Command-Line Help\n\nFor a complete list of available options:\n```bash\ndhcp-adguard-sync --help\ndhcp-adguard-sync sync --help\n```\n\nThis will show all available options, including `--lease-path` for the lease file path and `--lease-format` to select between \"isc\" and \"dnsmasq\" formats.\n\n## Uninstallation\n\n1. Stop and disable the service:\n```bash\nservice dhcp-adguard-sync stop\nservice dhcp-adguard-sync disable\n```\n\n2. Run the uninstall command:\n```bash\n# Keep configuration files\ndhcp-adguard-sync uninstall\n\n# Remove configuration files as well\ndhcp-adguard-sync uninstall --remove-config\n\n# Force uninstallation if experiencing issues\ndhcp-adguard-sync uninstall --force\n```\n\n## 🔧 Troubleshooting\n\n### Quick Diagnostics\n\n```bash\n# Check if service is running\nservice dhcp-adguard-sync status\n\n# Test configuration\ndhcp-adguard-sync sync --dry-run\n\n# View recent logs\ntail -50 /var/log/dhcp-adguard-sync.log\n```\n\n### Common Issues \u0026 Solutions\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🚫 Service won't start\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Service fails to start or immediately stops\n**Solutions**:\n1. Check configuration file exists: `ls -la /usr/local/etc/dhcp-adguard-sync/config.yaml`\n2. Verify binary permissions: `ls -la /usr/local/bin/dhcp-adguard-sync`\n3. Check logs: `grep dhcp-adguard-sync /var/log/messages`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔌 No clients appearing in AdGuard Home\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Service runs but no devices show up in AdGuard Home\n**Solutions**:\n1. Verify AdGuard credentials work: Test login at AdGuard Home web interface\n2. Check DHCP lease file: `ls -la /var/db/dnsmasq.leases` (or `/var/dhcpd/var/db/dhcpd.leases` for ISC)\n3. Confirm lease format matches your DHCP server\n4. Run test sync: `dhcp-adguard-sync sync --dry-run`\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔄 Sync happens but clients disappear\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Devices appear briefly then vanish from AdGuard Home\n**Solutions**:\n1. Enable \"Preserve Deleted Hosts\" in plugin settings\n2. Check for conflicting AdGuard Home settings\n3. Verify DHCP lease renewal times aren't too short\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e📡 IPv6 devices not syncing\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Only IPv4 devices appear in AdGuard Home\n**Solutions**:\n1. Ensure IPv6 is enabled in OPNsense DHCP settings\n2. Check NDP table: `ndp -a`\n3. Verify IPv6 DHCP leases exist\n\u003c/details\u003e\n\n### Enable Debug Mode\n\nFor detailed troubleshooting, enable debug logging:\n\n**Via Web UI**: Navigate to Services \u003e DHCP AdGuard Sync \u003e Enable Debug Mode\n**Via CLI**: Edit config file and set `LOG_LEVEL=\"debug\"`, then restart service\n\n### Getting Help\n\nIf issues persist:\n1. Enable debug logging\n2. Reproduce the issue\n3. Collect logs: `tail -100 /var/log/dhcp-adguard-sync.log`\n4. [Open an issue](https://github.com/jeeftor/opnsense-lease-sync/issues) with logs and configuration details\n\n## Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n## License\n\nMIT License - see LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeeftor%2Fdhcp-adguard-sync","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeeftor%2Fdhcp-adguard-sync","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeeftor%2Fdhcp-adguard-sync/lists"}