diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..2a20de9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2024 DNS Service Contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/README.md b/README.md index 3a09b86..dbc5023 100644 --- a/README.md +++ b/README.md @@ -1,83 +1,371 @@ -# DNS_SERVICE (frontend for dnsmasq) +# DNS Service -- [routes](#routes) -- [build](#build) -- [configure](#configure) - - [example](#example) -- [requests responses](#requests-responses) - - [/api/settings](#settings) - - [/api/settings/file](#settingsfile) +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. -## routes +## Features -- `GET` `/` - frontend -- `GET` `/api/settings` - get all settings -- `POST` `/api/settings` - set all settings -- `GET` `/api/settings/file` - get settings file content -- `POST` `/api/settings/file` - set settings file content +- **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 -## build +## Prerequisites -```shell -go build +- 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 ``` -## configure - -### example - +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 ``` -## requests-responses +### Configuration Parameters -### settings +| 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 | -#### `/api/settings` +### 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" - ] + "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" + ] } ``` -### settingsfile +#### Update Settings -#### `/api/settings/file` +```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. \ No newline at end of file