# DNS Service A Go-based web frontend for managing dnsmasq DNS server configurations. This service provides a RESTful API and web interface for dynamically managing DNS settings, host mappings, and resolver configurations. ## Features - **Web Interface**: Clean, responsive frontend for managing DNS settings - **RESTful API**: JSON-based API for programmatic configuration management - **Dynamic Configuration**: Real-time updates to dnsmasq configuration - **Host Management**: Easy management of hostname-to-IP mappings - **Resolver Configuration**: Flexible DNS resolver settings - **TLS Support**: Optional HTTPS/TLS encryption - **Service Integration**: Systemd-compatible service management - **Cache Control**: Configurable DNS cache size settings ## Prerequisites - Go 1.24.4 or higher - dnsmasq installed and configured - Linux system with systemd (for service management) - SSL certificates (for TLS mode) ## Installation ### From Source 1. Clone the repository: ```bash git clone cd dns_service ``` 2. Build the application: ```bash go build -o dns_service ``` 3. Install the binary: ```bash sudo cp dns_service /usr/bin/ sudo chmod +x /usr/bin/dns_service ``` 4. Create configuration directory: ```bash sudo mkdir -p /etc/dns_service ``` 5. Copy configuration files: ```bash sudo cp dns_service.conf /etc/dns_service/ sudo cp dns_service.service /etc/init.d/ sudo chmod +x /etc/init.d/dns_service.service ``` ## Configuration ### Environment Variables The service is configured via environment variables in `/etc/dns_service/dns_service.conf`: ```bash # dnsmasq configuration file path DNSMASQ_CONFIG=/etc/dnsmasq.conf # TLS configuration ENABLE_TLS=true CERT_FILE=/etc/dns_service/dns.home.com.crt KEY_FILE=/etc/dns_service/dns.home.com.key # Server configuration SERVER_ADDRESS=0.0.0.0 SERVER_PORT=8090 # System initialization type SYSTEM_INITIALIZATION=rc ``` ### Configuration Parameters | Parameter | Description | Default | Required | |-----------|-------------|---------|----------| | `DNSMASQ_CONFIG` | Path to dnsmasq configuration file | `/etc/dnsmasq.conf` | Yes | | `ENABLE_TLS` | Enable HTTPS/TLS encryption | `false` | No | | `CERT_FILE` | Path to SSL certificate file | - | If TLS enabled | | `KEY_FILE` | Path to SSL private key file | - | If TLS enabled | | `SERVER_ADDRESS` | Server bind address | `0.0.0.0` | No | | `SERVER_PORT` | Server port | `8090` | No | | `SYSTEM_INITIALIZATION` | Init system type | `rc` | No | ### TLS Setup For TLS mode, ensure you have valid SSL certificates: ```bash # Generate self-signed certificate (for testing) sudo openssl req -x509 -newkey rsa:4096 -keyout /etc/dns_service/dns.home.com.key \ -out /etc/dns_service/dns.home.com.crt -days 365 -nodes # Set proper permissions sudo chmod 600 /etc/dns_service/dns.home.com.key sudo chmod 644 /etc/dns_service/dns.home.com.crt ``` ## API Documentation ### Endpoints | Method | Endpoint | Description | |--------|----------|-------------| | `GET` | `/` | Web frontend interface | | `GET` | `/api/settings` | Get current DNS settings | | `POST` | `/api/settings` | Update DNS settings | | `GET` | `/api/settings/file` | Get raw dnsmasq configuration | | `POST` | `/api/settings/file` | Update raw dnsmasq configuration | ### API Examples #### Get Current Settings ```bash curl -X GET http://localhost:8090/api/settings ``` **Response:** ```json { "cache_size": 10000, "hosts": { "185.130.83.26": "gitea.home.com", "192.168.3.1": "router.home.com", "192.168.3.113": [ "samba.home.com", "gitea.home.com", "navidrome.home.com" ], "192.168.3.119": [ "immich.home.com", "jellyfin.home.com", "portainer.home.com" ], "192.168.3.155": "dns.home.com" }, "resolv": [ "192.168.3.1", "109.194.32.1", "5.3.3.3", "8.8.8.8" ] } ``` #### Update Settings ```bash curl -X POST -H "Content-Type: application/json" \ -d '{"cache_size": 15000, "hosts": {"192.168.1.100": "server.local"}, "resolv": ["8.8.8.8", "8.8.4.4"]}' \ http://localhost:8090/api/settings ``` #### Get Configuration File ```bash curl -X GET http://localhost:8090/api/settings/file ``` **Response:** ``` resolv-file=/etc/dnsmasq.conf.d/resolv.conf addn-hosts=/etc/dnsmasq.conf.d/hosts cache-size=10000 ``` #### Update Configuration File ```bash curl -X POST -H "Content-Type: text/plain" \ -d "resolv-file=/etc/dnsmasq.conf.d/resolv.conf addn-hosts=/etc/dnsmasq.conf.d/hosts cache-size=15000" \ http://localhost:8090/api/settings/file ``` ## Service Management ### Start the Service ```bash # Manual start sudo /etc/init.d/dns_service.service start # Or run directly sudo /usr/bin/dns_service ``` ### Stop the Service ```bash sudo /etc/init.d/dns_service.service stop ``` ### Restart the Service ```bash sudo /etc/init.d/dns_service.service restart ``` ### Check Service Status ```bash # Check if process is running ps aux | grep dns_service # Check process ID cat /var/run/dns_service.pid ``` ## Development ### Project Structure ``` dns_service/ ├── api/ # API handlers and frontend │ ├── frontend/ # Web frontend assets │ ├── settings.go # Settings API handler │ ├── settings_file.go # Configuration file handler │ └── spa.go # Single-page application handler ├── settings/ # Settings management │ ├── get_settings.go # Get settings functionality │ └── set_settings.go # Set settings functionality ├── utils/ # Utility functions │ ├── decode_hosts.go # Host parsing utilities │ ├── decode_resolvs.go # Resolver parsing utilities │ ├── decode_settings.go # Settings parsing utilities │ ├── response_json.go # JSON response utilities │ └── restart_dnsmasq.go # dnsmasq restart functionality ├── main.go # Application entry point ├── go.mod # Go module definition ├── go.sum # Go module checksums ├── dns_service.conf # Configuration file ├── dns_service.service # Init script └── README.md # This file ``` ### Building ```bash # Build for current platform go build -o dns_service # Build for Linux (cross-compilation) GOOS=linux GOARCH=amd64 go build -o dns_service # Build with version information go build -ldflags "-X main.version=1.0.0" -o dns_service ``` ### Testing ```bash # Run tests go test ./... # Test with coverage go test -cover ./... # Test specific package go test ./api ``` ### Dependencies The project uses minimal external dependencies: - `github.com/joho/godotenv` - Environment variable loading ## Usage Examples ### Basic DNS Setup 1. Configure your local domains in the web interface 2. Set upstream DNS servers (Google DNS, Cloudflare, etc.) 3. Configure cache size based on your needs 4. Apply settings and restart dnsmasq ### Home Network Setup Perfect for home labs and local development: ```json { "cache_size": 10000, "hosts": { "192.168.1.100": ["homelab.local", "api.homelab.local"], "192.168.1.101": "nas.local", "192.168.1.102": "router.local" }, "resolv": ["192.168.1.1", "8.8.8.8", "1.1.1.1"] } ``` ### Corporate Network Setup ```json { "cache_size": 50000, "hosts": { "10.0.1.100": ["intranet.corp.local", "wiki.corp.local"], "10.0.1.101": "mail.corp.local", "10.0.1.102": "files.corp.local" }, "resolv": ["10.0.1.1", "8.8.8.8"] } ``` ## Security Considerations - Always use TLS in production environments - Restrict access to the management interface - Use strong SSL certificates from a trusted CA - Regularly update the service and dependencies - Monitor logs for suspicious activity - Consider firewall rules to limit access ## Troubleshooting ### Common Issues 1. **Service won't start**: Check configuration file syntax and permissions 2. **TLS errors**: Verify certificate files and permissions 3. **Port conflicts**: Ensure port 8090 is not in use by another service 4. **dnsmasq integration**: Verify dnsmasq is installed and properly configured ### Logs Check system logs for error messages: ```bash # Check service logs journalctl -u dns_service # Check dnsmasq logs journalctl -u dnsmasq # Check application logs tail -f /var/log/dns_service.log ``` ## Contributing 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit your changes (`git commit -m 'Add some amazing feature'`) 4. Push to the branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request ## License This project is licensed under the MIT License - see the LICENSE file for details. ## Support For support and questions: - Create an issue in the repository - Check the documentation - Review existing issues and discussions --- **Note**: This service is designed to work with dnsmasq. Ensure dnsmasq is properly installed and configured before using this frontend.