This commit is contained in:
@@ -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.
|
||||
@@ -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 <repository-url>
|
||||
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.
|
||||
Reference in New Issue
Block a user