dns_service/README.md

# 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 <repository-url>
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.