dns_service_c/README.md

# DNS Service

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

A lightweight DNS management service written in C with a web-based interface for configuring DNS settings and managing dnsmasq configuration.

## Features

- **Web Interface**: Modern responsive web UI for DNS configuration
- **DNS Settings Management**: Configure upstream DNS servers, local domains, and cache settings
- **DHCP Configuration**: Enable/disable DHCP with range configuration
- **File Management**: Direct editing of configuration files
- **SSL/TLS Support**: Optional HTTPS with certificate configuration
- **JSON Configuration**: Easy-to-manage JSON-based configuration
- **Cross-platform**: Supports multiple build systems (Make, CMake, Meson)

## Architecture

The service consists of:
- **HTTP/HTTPS Server**: Built on Mongoose web server
- **REST API**: JSON-based API for configuration management
- **Web Interface**: Bootstrap-based responsive UI
- **Configuration Parser**: Custom dnsmasq config parser
- **File Operations**: Safe file reading/writing utilities

## API Endpoints

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/settings` | Get current DNS settings |
| POST | `/api/settings` | Update DNS settings |
| GET | `/api/settings/file` | Get raw configuration file |
| POST | `/api/settings/file` | Update configuration file |
| GET | `/#` | Serve web interface |

## Requirements

### Build Dependencies
- GCC compiler with C23 support
- OpenSSL development libraries
- pthread library

### System Dependencies
- dnsmasq (for DNS service functionality)
- SSL certificates (for HTTPS support)

## Installation

### Using Make
```bash
make
```

### Using CMake
```bash
mkdir build && cd build
cmake ..
make
```

### Using Meson
```bash
meson setup builddir
meson compile -C builddir
```

## Configuration

Edit `config.json` to configure the service:

```json
{
    "address": "0.0.0.0:8321",
    "tls_address": "0.0.0.0:8322",
    "web": "./web",
    "tls_enabled": true,
    "tls_cert": "/path/to/certificate.crt",
    "tls_key": "/path/to/private.key",
    "system_initialization": "rc",
    "dnsmasq_config": "/etc/dnsmasq.conf"
}
```

### Configuration Parameters

- `address`: HTTP server bind address and port
- `tls_address`: HTTPS server bind address and port
- `web`: Path to web interface files
- `tls_enabled`: Enable/disable HTTPS support
- `tls_cert`: Path to SSL certificate file
- `tls_key`: Path to SSL private key file
- `system_initialization`: System initialization type
- `dnsmasq_config`: Path to dnsmasq configuration file

## Usage

### Starting the Service
```bash
./dns_service
```

The service will start HTTP server on the configured address (default: `0.0.0.0:8321`) and optionally HTTPS server if TLS is enabled.

### Web Interface

Navigate to `http://localhost:8321` (or your configured address) to access the web interface where you can:

- Configure upstream DNS servers
- Manage local domain mappings
- Enable/disable DHCP with range settings
- Adjust DNS cache size
- Edit configuration files directly

### API Usage

#### Get Current Settings
```bash
curl -X GET http://localhost:8321/api/settings
```

#### Update Settings
```bash
curl -X POST http://localhost:8321/api/settings \
  -H "Content-Type: application/json" \
  -d '{"cache_size": 1000, "resolv": ["8.8.8.8", "8.8.4.4"]}'
```

## Development

### Project Structure
```
dns_service_c/
├── src/
│   ├── lib/           # Third-party libraries
│   │   ├── mongoose.c # HTTP server
│   │   ├── cJSON.c    # JSON parser
│   │   └── ...
│   ├── main.c         # Application entry point
│   ├── config.c       # Configuration management
│   ├── settings.c     # DNS settings handlers
│   └── ...
├── web/               # Web interface files
│   ├── index.html
│   ├── css/
│   └── js/
├── config.json        # Service configuration
└── README.md
```

### Building for Development
```bash
# With debug symbols
make CFLAGS="-Wall -g -std=gnu2x -DDEBUG"

# Clean build
make clean && make
```

### Code Style
The project uses `.clang-format` for consistent code formatting:
```bash
clang-format -i src/*.c src/*.h
```

## Security Considerations

- The service runs with system privileges to modify DNS configuration
- HTTPS is strongly recommended for production deployments
- Ensure proper file permissions on certificate files
- Consider firewall rules to restrict access to management interface

## Troubleshooting

### Common Issues

1. **Permission denied when accessing dnsmasq config**
   - Ensure the service has read/write permissions to the dnsmasq configuration file
   - Run with appropriate privileges or adjust file permissions

2. **SSL/TLS certificate errors**
   - Verify certificate and key file paths in `config.json`
   - Ensure certificate files have correct permissions
   - Check certificate validity and format

3. **Port binding errors**
   - Verify ports are not already in use
   - Check firewall settings
   - Ensure proper privileges for binding to privileged ports

### Logging
The service uses Mongoose's built-in logging. Set log level in code or use debug build for verbose output.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes following the existing code style
4. Test your changes thoroughly
5. Submit a pull request

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

### Third-party Libraries

This project includes the following third-party libraries:

- **Mongoose**: HTTP/WebSocket server library
- **cJSON**: JSON parser library

Please refer to their respective licenses for usage terms.

## Support

For issues and questions, please check the project's issue tracker or documentation.