dns_service_c/README.md

DNS Service

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

make

Using CMake

mkdir build && cd build
cmake ..
make

Using Meson

meson setup builddir
meson compile -C builddir

Configuration

Edit config.json to configure the service:

{
    "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

./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

curl -X GET http://localhost:8321/api/settings

Update Settings

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

# 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:

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 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.